Neptune Diagnostics

Neptune Diagnostics

When to use

Any Amazon Neptune investigation where the console alone is insufficient — cluster health analysis, query performance debugging, connectivity troubleshooting, replication monitoring, backup/restore, serverless scaling, data migration, or security configuration.

Investigation workflow

Step 1 — Collect and triage

aws neptune describe-db-clusters
aws neptune describe-db-clusters --db-cluster-identifier <cluster-id>
aws neptune describe-db-instances --filters Name=db-cluster-id,Values=<cluster-id>
aws cloudwatch get-metric-statistics --namespace AWS/Neptune --metric-name CPUUtilization --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/Neptune --metric-name FreeableMemory --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/Neptune --metric-name GremlinRequestsPerSec --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Sum

Step 2 — Domain deep dive

aws neptune describe-events --source-type db-cluster --duration 1440
aws neptune describe-events --source-type db-instance --duration 1440
aws neptune describe-db-cluster-parameters --db-cluster-parameter-group-name <param-group>
aws neptune describe-db-cluster-endpoints --db-cluster-identifier <cluster-id>
curl -X POST https://<cluster-endpoint>:8182/gremlin -d '{"gremlin":"g.V().count()"}'
curl -X POST https://<cluster-endpoint>:8182/sparql -d 'query=SELECT (COUNT(*) AS ?count) WHERE { ?s ?p ?o }'
curl https://<cluster-endpoint>:8182/status

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=rds.amazonaws.com --max-results 20
aws neptune describe-db-cluster-snapshots --db-cluster-identifier <cluster-id>
aws neptune describe-db-subnet-groups --db-subnet-group-name <subnet-group>
aws ec2 describe-security-groups --group-ids <sg-id>
aws cloudwatch get-metric-statistics --namespace AWS/Neptune --metric-name VolumeBytesUsed --dimensions Name=DBClusterIdentifier,Value=<cluster-id> --start-time <start> --end-time <end> --period 300 --statistics Average
aws neptune describe-global-clusters

Read references/neptune-guardrails.md before concluding on any Neptune issue.

Tool quick reference

Gotchas: Amazon Neptune

• Neptune is VPC-only — there is no public endpoint. All access must be from within the VPC, through a VPC endpoint, a bastion host, or an SSH tunnel. There is no option to enable public accessibility like RDS. This is a fundamental architectural constraint.
• Gremlin and SPARQL are different query languages on the same engine. Neptune supports both Apache TinkerPop Gremlin (property graph) and W3C SPARQL (RDF). Both run on the same cluster but use different data models. You cannot query Gremlin data with SPARQL or vice versa. Choose one model per use case.
• Bulk loader uses S3 for data ingestion. The Neptune bulk loader reads data from S3 buckets. It requires an IAM role with S3 access attached to the Neptune cluster. The loader supports CSV (Gremlin) and N-Triples/N-Quads/Turtle/RDF-XML (SPARQL). Direct data loading via queries is much slower.
• IAM authentication requires SigV4 signing. When IAM auth is enabled, all requests must be signed with AWS Signature Version 4. This applies to both Gremlin and SPARQL endpoints. Standard HTTP clients need SigV4 signing libraries. The Gremlin console requires special configuration for IAM auth.
• Neptune Serverless has a different scaling model. Neptune Serverless scales capacity in Neptune Capacity Units (NCUs). It scales based on workload demand between min and max NCU settings. Scaling is not instantaneous — there can be brief pauses during scale-up. Cost is based on NCUs consumed.
• No cross-region read replicas — use global database. Neptune does not support cross-region read replicas like Aurora. For cross-region disaster recovery or read scaling, use Neptune Global Database which replicates the entire cluster to secondary regions with typical lag under 1 second.
• Neptune notebooks provide integrated exploration. Neptune Workbench (Jupyter notebooks) provides an integrated environment for graph exploration with visualization. Notebooks connect directly to the cluster endpoint and support both Gremlin and SPARQL with built-in graph visualization.

Anti-hallucination rules

1. Always cite specific cluster IDs, instance IDs, CloudWatch metrics, or query output as evidence.
2. Neptune is VPC-only. Never suggest enabling public access or connecting without VPC/tunnel.
3. Gremlin and SPARQL are separate data models. Never suggest cross-querying between them.
4. IAM auth requires SigV4. Never suggest simple username/password auth for Neptune.
5. No cross-region read replicas. Always recommend global database for cross-region needs.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

24 runbooks