Levandor

grafeo — Feature Matrix & the Silent-Tracing Gotcha

3 min read

grafeo v0.5.42 is the embeddable graph database backing ai-project-brain. Its Cargo feature split is a genuine fork in the road — embedded vs server vs edge are three different products — and the split is not visible from the crate’s docs.rs page. This note records the matrix and the one feature whose absence costs real debugging time.

The gotcha: grafeo is silent in your logs by default

tracing is an opt-in grafeo feature (tracing = ["grafeo-engine/tracing"]), NOT part of embedded or default.

Symptom: you have tracing_subscriber initialized and working, your own tracing::info! calls appear, but the graph layer emits no spans and no events whatsoever. Nothing errors. There is no warning. The graph engine is simply absent from the log stream, which reads exactly like “the query never ran” or “the subscriber is misconfigured”.

Why it burns time: the natural debugging path is to suspect the subscriber (EnvFilter directives, RUST_LOG, init ordering, a second subscriber) — all of which are fine. The instrumentation was never compiled in.

Fix: add the feature to the grafeo entry in the root [workspace.dependencies]:

grafeo = { version = "0.5.42", features = ["tracing"] }

Feature Matrix

FeatureExpands toWhat you get
default = ["embedded"]grafeo-engine/lpg, gql, ai, algos, parallel, regex, grafeo-file, arrow-exportIn-process graph engine. GQL, vector / text / hybrid indexes, CDC, graph algorithms, rayon parallelism
serverembedded plus all query languages (cypher, sparql, gremlin, graphql, sql-pgq), async-storage, triple-store, shacl, tracingFull server-mode deployment. full = ["server"]
edge / browserlpg + gql + regex-lite onlyStripped down for wasm / edge targets
tracing (standalone)grafeo-engine/tracing⭐ Opt-in. Emits spans/events into the app’s tracing_subscriber. See the callout above

For Agents

Note that tracing arrives for free with server but not with embedded. That asymmetry is the trap: reading “server includes tracing” does not tell you that the default does not. If you are on embedded and want observability, you must name the feature explicitly.

Current State in This Workspace

⚠️ ai-project-brain runs grafeo on default features (embedded) — the in-process choice. The root Cargo.toml entry carries no features key:

[workspace.dependencies]
grafeo = "0.5.42"

Consequences, all deliberate:

  • ✅ In-process engine — no server process, no network hop
  • ⛔ No server-mode query languages — no Cypher, SPARQL, Gremlin, GraphQL or SQL/PGQ. GQL only
  • ⛔ No tracing integration — the graph layer is invisible in logs

That last point is live right now, not hypothetical: packages/app/src/main.rs already initializes a subscriber that grafeo would emit into if the feature were on —

tracing_subscriber::fmt()
    .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info")))
    .init();

So the receiving end is wired and working; only the sending end is compiled out. The first person to debug a graph query in this workspace will hit this.

Graph View

Backlinks