telemetry.md

Telemetry (OpenTelemetry)

repolens instruments its build pipeline with the OTel API and stays a strict no-op unless you install the [otel] extra and configure an SDK/exporter — the library never configures an exporter itself, and without the SDK the overhead is zero (inert stand-in objects).

Enable

pip install "repolens[otel]"
# then configure the SDK in YOUR process, e.g. via environment auto-config:
pip install opentelemetry-exporter-otlp
export OTEL_SERVICE_NAME=repolens-indexer
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
opentelemetry-instrument repolens build --manifest repolens.yaml

or programmatically before calling build_all():

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

from repolens import build_all
build_all("repolens.yaml")

What you get

Span tree (tracer name repolens):

repolens.build              attrs: repolens.out_dir, repolens.dry_run
├── repolens.meta
├── repolens.index.code     attrs: repolens.files.indexed, repolens.chunks.written
├── repolens.index.docs     (skipped without a docs: section)
└── repolens.graph          attrs: repolens.graph.nodes, repolens.graph.edges

Counters (meter repolens, attribute corpus=code|docs):

Counter	Meaning
repolens.files.scanned	non-empty files walked
repolens.files.indexed	files (re)embedded this run
repolens.chunks.written	rows written to the store
repolens.tokens.estimated	dry-run token estimate

The BuildReport returned by build_all() carries the same numbers — OTel is a mirror for your dashboards, not the source of truth, so nothing breaks when it is disabled.