Skip to main content
⏳ Estimated read time: 3 min read

Neo4j

Neo4j

Neo4j AuraDB is a fully managed service, so there is no in-cluster endpoint to scrape. Instead, Aura exposes a Prometheus-compatible Customer Metrics Integration (CMI) endpoint, and the StackGen agent scrapes it over the internet using OAuth2.

Integration is two steps: (1) enable metrics on the Neo4j side and get API credentials, and (2) add a scrape job (and its secret) to the agent's values.yaml.

note

CMI is available on AuraDB Business Critical and Enterprise (Virtual Dedicated Cloud) instances.

1. Enable metrics in Neo4j (Aura Console)​

  1. Create a metrics user. In the Aura Console, go to User Management and invite a user (or service account) with the Metrics Integration Reader role.

    warning

    An Admin or Project role is not sufficient on its own — the metrics role must be granted explicitly. Otherwise the endpoint returns 401 User doesn't have access to Metrics resources.

  2. Create API credentials. Logged in as that user, go to Account → API Credentials and create a key. Save the Client ID and Client Secret (the secret is shown only once).

  3. Copy the metrics endpoint. On the instance's Metrics Integration screen, enable metrics (granularity Comprehensive adds availability_zone and instance_mode labels) and copy the endpoint URL:

    https://customer-metrics-api.neo4j.io/api/v1/<projectId>/<instanceId>/metrics

2. Configure the agent (values.yaml)​

Neo4j Aura is an external SaaS target secured with OAuth2, so it is added as a static_configs scrape job (not Kubernetes service discovery). Add the job under extraScrapeConfigs and reference the client secret via client_secret_file.

victoria-metrics-agent:
  extraScrapeConfigs:
    - job_name: 'neo4j-aura'
      scheme: https
      scrape_interval: 1m
      scrape_timeout: 30s
      metrics_path: '/api/v1/<projectId>/<instanceId>/metrics'   # from the Aura console
      static_configs:
        - targets: ['customer-metrics-api.neo4j.io']
      oauth2:
        client_id: '<AURA_CLIENT_ID>'
        client_secret_file: /etc/vmagent-credentials/neo4j-aura-secret
        token_url: 'https://api.neo4j.io/oauth/token'

Add the client secret as a key in the credentials secret the agent already mounts at /etc/vmagent-credentials:

kubectl -n <observe-namespace> patch secret observe-agent-credentials \
  --type merge \
  -p '{"stringData":{"neo4j-aura-secret":"<AURA_CLIENT_SECRET>"}}'
warning

If the key referenced by client_secret_file is missing, the agent rejects the config reload and silently keeps the previous config — the neo4j-aura job will not appear. Ensure the secret key exists, then roll the agent.

Apply the values and run the agent based on these instructions. Within one scrape interval the metrics appear prefixed neo4j_ (for example neo4j_database_count_node, neo4j_dbms_page_cache_hit_ratio_per_minute, neo4j_db_query_execution_internal_latency_q99). Series are labelled with instance_id, database, instance_mode (PRIMARY/SECONDARY), availability_zone, and aggregation.

Verify​

Confirm the target is up and metrics are flowing:

up{job="neo4j-aura"}          # expect 1
neo4j_database_count_node     # node count per instance
note

Gauge metrics carry aggregation="MAX" (identical across availability zones — collapse with max by (instance_id)), while counters carry aggregation="SUM" per zone (total with sum by (instance_id)).

Last updated on