Neo4J Tracing

Introduction

neo4jtracing is a go library that enables otel distribute tracing for neo4j driver v6.

Getting Started

Add this library as a dependency via go get github.com/collibra/go-neo4j-tracing

Enable tracing

Tracing can be enabled by using the neo4j_tracing.Neo4jTracer object. The Neo4jTracer a factory that creates neo4j.DriverWithContext objects that are wrapped so distributed tracing can be applied.

Start using tracing is very easy. A regular neo4j driver will be created as follows:

package main

import (
	"github.com/neo4j/neo4j-go-driver/v6/neo4j"
)

func main() {
    dbUri := "neo4j://localhost" // scheme://host(:port) (default port is 7687)
    driver, err := neo4j.NewDriver(dbUri, neo4j.BasicAuth("neo4j", "letmein!", ""))
    if err != nil {
        panic(err)
    }
    // Do something useful
}

To enable tracing you need to create your driver by using the Neo4jTracer object.

package main

import (
    "github.com/neo4j/neo4j-go-driver/v6/neo4j"
    neo4j_tracing "github.com/collibra/go-neo4j-tracing"
)

func main() {
    driverFactory := neo4j_tracing.NewNeo4jTracer()

    dbUri := "neo4j://localhost" // scheme://host(:port) (default port is 7687)
    driver, err := driverFactory.NewDriver(dbUri, neo4j.BasicAuth("neo4j", "letmein!", ""))
    if err != nil {
        panic(err)
    }
    // Do something useful
}

Options

The following options could be used to customize the tracing and metrics behavior:

• WithTracerProvider(provider): Specifies a custom tracer provider. By default, the global OpenTelemetry tracer provider is used.
• WithMeterProvider(provider): Specifies a meter provider to use for recording metrics. If none is specified, metrics are not recorded.

Those options are passed as argument to the neo4j_tracing.NewNeo4jTracer() function.

Enable metrics

Metrics can be enabled by passing a WithMeterProvider option to the NewNeo4jTracer function:

package main

import (
    "github.com/neo4j/neo4j-go-driver/v6/neo4j"
    neo4j_tracing "github.com/collibra/go-neo4j-tracing"
    sdkmetric "go.opentelemetry.io/otel/sdk/metric"
)

func main() {
    // Set up your meter provider (e.g., with an OTLP exporter)
    mp := sdkmetric.NewMeterProvider()
    defer mp.Shutdown(context.Background())

    driverFactory := neo4j_tracing.NewNeo4jTracer(
        neo4j_tracing.WithMeterProvider(mp),
    )

    dbUri := "neo4j://localhost"
    driver, err := driverFactory.NewDriver(dbUri, neo4j.BasicAuth("neo4j", "letmein!", ""))
    if err != nil {
        panic(err)
    }
    // Do something useful
}

Available metrics

Core metrics (recorded for every operation)

Metric	Type	Description
db.client.operation.duration	Float64Histogram (seconds)	Client-side duration of each operation
db.client.operation.count	Int64Counter	Total number of operations executed
db.client.error.count	Int64Counter	Total number of failed operations

Common attributes: db.system.name="neo4j", db.operation.name, db.namespace, server.address, error.type (on failure).

ResultSummary metrics (recorded on Consume() / Single() calls)

Metric	Type	Description
db.client.result.available_after	Float64Histogram (seconds)	Server-side time until result was available
db.client.result.consumed_after	Float64Histogram (seconds)	Server-side time to consume result
db.client.result.nodes_created	Int64Counter	Cumulative nodes created
db.client.result.nodes_deleted	Int64Counter	Cumulative nodes deleted
db.client.result.relationships_created	Int64Counter	Cumulative relationships created
db.client.result.relationships_deleted	Int64Counter	Cumulative relationships deleted
db.client.result.properties_set	Int64Counter	Cumulative properties set
db.client.result.labels_added	Int64Counter	Cumulative labels added
db.client.result.labels_removed	Int64Counter	Cumulative labels removed
db.client.result.indexes_added	Int64Counter	Cumulative indexes added
db.client.result.indexes_removed	Int64Counter	Cumulative indexes removed
db.client.result.constraints_added	Int64Counter	Cumulative constraints added
db.client.result.constraints_removed	Int64Counter	Cumulative constraints removed
db.client.result.system_updates	Int64Counter	Cumulative system updates

Session lifecycle metrics

Metric	Type	Description
db.client.session.count	Int64Counter	Total sessions created
db.client.session.active	Int64UpDownCounter	Currently active sessions

Attributes: db.system.name="neo4j", server.address.

Transaction lifecycle metrics

Metric	Type	Description
db.client.transaction.count	Int64Counter	Total transactions started
db.client.transaction.commit.count	Int64Counter	Committed transactions
db.client.transaction.rollback.count	Int64Counter	Rolled back transactions

Attributes: db.system.name="neo4j", db.namespace, server.address.