Skip to content

Community and Launch

Semconv Graph should be introduced through a reproducible problem and result, not through its dependency list.

One-sentence description

Semconv Graph turns existing OpenTelemetry traces into a live typed entity graph without changing application instrumentation.

The supporting sentence is:

It combines service interaction evidence with opt-in spanmetrics evidence from non-client/non-server roots in one contributor-aware lifecycle engine.

Demonstration story

A useful public demo should take one observable interaction from input to query:

  1. Show paired client/server spans from applications with ordinary OTel trace instrumentation.
  2. Show the Collector producing service-graph delta metrics.
  3. Show Flink extracting shared nodes and edges and merging complementary contributor fields.
  4. Query the current graph through typed Gremlin.
  5. Stop one contributor and show shared elements remain.
  6. Stop the final contributor and show explicit graph-element deletion.
  7. Emit repeated non-interacting execution roots and show spanmetrics collapse them into transaction and observation-topology discovery without exporting raw spans to Kafka.

Use concrete services, IDs, attributes, and traversals. The repository's controlled Java workload measurements are reproducible, but avoid production capacity or cost claims until those paths are measured.

Presentation outline

1. Problem

Traces describe requests, but many teams lack a continuously maintained, semantically typed inventory and dependency graph.

2. Adoption constraint

Requiring every application or infrastructure observer to emit a new entity signal delays value. Existing trace telemetry can provide a useful initial graph.

3. Working implementation

Explain trace-affine Collector routing, generated semantic extraction, Flink contributor state, the compacted lifecycle stream, ArangoDB projection, and read-only Gremlin.

4. Live proof

Run the focused environment or a prepared complete deployment. Show upsert, shared-contributor survival, final expiry, replay, and typed query results.

5. OpenTelemetry alignment

Reference the official Entity Data Model and semantic conventions. Present servicegraph and spanmetrics datapoints as freshness evidence for one typed graph.

6. Honest boundaries

State that standard output, incoming-relationship implicit deletion, historical queries, and public scale benchmarks are not complete.

7. Contribution request

Ask for help on a small number of bounded problems rather than asking people to "improve the project."

Contribution tracks

Good independent contribution areas are:

  • incoming-relationship cleanup, schema_url, and identification-context work;
  • additional semantic entity and relationship extensions;
  • benchmark scenarios and measurement tooling;
  • Collector deployment examples for existing environments;
  • operational signals for Flink state, Kafka lag, and ArangoDB projection;
  • documentation for Java, Go, or raw Gremlin clients;
  • validation on Kubernetes distributions and restricted security policies.

Changes to lifecycle state, deterministic IDs, or the Kafka schema need a design discussion because they affect recovery and downstream consumers.

Evidence needed before scale claims

Publish a distributed benchmark before describing the complete system as cheaper or more scalable than alternatives. At minimum record:

  • source datapoints and resulting contributions per second;
  • end-to-end upsert and delete latency;
  • Flink keyed-state size by active contributor and graph-element count;
  • Kafka partition count, parallelism, and replay time;
  • indexer throughput and ArangoDB write latency;
  • CPU and memory per component;
  • dataset, topology, configuration, and exact image versions.

Architecture provides a scaling mechanism; these measurements establish its actual operating envelope.

Launch checklist

  • Keep the product statement and limitations visible in the README.
  • Record a short demo using the same commands documented in the quickstart.
  • Publish immutable wheels, images, and chart versions when release automation exists.
  • Open bounded issues for the contribution tracks above.
  • Label introductory issues only when a maintainer can explain and review them.
  • Bring a running demo to the OpenTelemetry Entities SIG for technical feedback.
  • Turn accepted design decisions into tests and documentation before broadening compatibility claims.

The launch target is not maximum attention. It is enough clarity that an engineer can reproduce the graph, identify an honest gap, and contribute to it without first reverse-engineering the repository.