Neo4j — Setup Documentation and Observability (issue 19 of 29)

Labels: ready-to-code
Depends on: Issue 17 (#TBD core sync adapter), Issue 18 (#TBD SkillBundle support)
RHIDP Stories: RHIDP-15301
Feature: RHDHPLAN-1507 — Epic RHIDP-15295

Write setup documentation (configuration examples, K8s Secret setup, graph schema reference, example Cypher queries), implement Prometheus metrics export (neo4j_sync_total, neo4j_sync_success, etc.), and add structured logging for sync cycles. Includes testing and performance optimization (batch writes, similarity throttling).

Tasks

From openspec/changes/neo4j-knowledge-graph/tasks.md group 6 (RHIDP-15301):

• 6.1 Write neo4j-sync-setup.md with configuration examples
• 6.2 Document K8s Secret setup for Neo4j credentials
• 6.3 Document manual sync trigger API usage
• 6.4 Write neo4j-graph-schema.md with node/relationship type tables
• 6.5 Document catalog-as-source-of-truth architecture
• 6.6 Document relationship derivation rules
• 6.7 Write examples/neo4j-queries.cypher with 5+ example queries

From openspec/changes/neo4j-knowledge-graph/tasks.md group 7 (RHIDP-15301):

• 7.1 Document sync failure troubleshooting steps
• 7.2 Document Neo4j connection troubleshooting
• 7.3 Document schema migration procedure
• 7.4 Implement Prometheus metrics export
• 7.5 Document Prometheus metrics and example Grafana queries
• 7.6 Add structured logging for sync cycles

From openspec/changes/neo4j-knowledge-graph/tasks.md groups 8–9:

• 8.1–8.7 Testing (revision tracking, relationship derivation, in-memory Neo4j, SkillBundle, Cypher queries, full sync rebuild, failure isolation)
• 9.1–9.6 Performance optimization (batch writes, similarity throttling, similarity threshold config, disable flag, profiling, performance tuning docs)

Specifications

• openspec/changes/neo4j-knowledge-graph/specs/setup-documentation/spec.md

Start with openspec/changes/neo4j-knowledge-graph/specs/setup-documentation/spec.md and tasks.md, including the stated dependencies on issues 17 and 18. Break the work into documentation, metrics and logging, testing, and performance areas, then verify that the requested setup guides, schema and query examples, observability features, tests, and tuning documentation are complete.