OpenTelemetry Setup
MATIH uses OpenTelemetry (OTel) for distributed tracing instrumentation across both Python and Java services. The OTel SDK captures spans for HTTP requests, database queries, Kafka operations, and LLM API calls, then exports them to the OTel Collector for forwarding to Tempo.
Python Services
Installation
pip install opentelemetry-api opentelemetry-sdk \
opentelemetry-instrumentation-fastapi \
opentelemetry-instrumentation-httpx \
opentelemetry-instrumentation-sqlalchemy \
opentelemetry-exporter-otlpConfiguration
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
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
# Configure provider
provider = TracerProvider(resource=Resource.create({
"service.name": "ai-service",
"service.namespace": "matih-data-plane",
"deployment.environment": os.getenv("ENVIRONMENT", "dev"),
}))
# Add OTLP exporter
exporter = OTLPSpanExporter(endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT"))
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
# Auto-instrument FastAPI
FastAPIInstrumentor.instrument_app(app)Custom Spans
tracer = trace.get_tracer("ai-service")
with tracer.start_as_current_span("llm_call") as span:
span.set_attribute("model.id", "gpt-4")
span.set_attribute("tokens.input", 1500)
span.set_attribute("tokens.output", 500)
result = await llm_client.generate(prompt)
span.set_attribute("tokens.total", result.total_tokens)Java Services
Spring Boot Configuration
management:
tracing:
sampling:
probability: 1.0
propagation:
type: W3C
otel:
exporter:
otlp:
endpoint: http://otel-collector:4317
resource:
attributes:
service.name: iam-service
service.namespace: matih-control-planeOTel Collector
The OpenTelemetry Collector receives spans from services and forwards them to Tempo:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch:
timeout: 5s
send_batch_size: 1000
exporters:
otlp:
endpoint: tempo:4317
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlp]Environment Variables
| Variable | Description | Default |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | OTel Collector endpoint | http://otel-collector:4317 |
OTEL_SERVICE_NAME | Service name for traces | Service-specific |
OTEL_TRACES_SAMPLER | Sampling strategy | parentbased_always_on |
OTEL_TRACES_SAMPLER_ARG | Sampling rate | 1.0 |
Sampling Strategy
| Environment | Strategy | Rate |
|---|---|---|
| Development | always_on | 100% |
| Staging | parentbased_traceidratio | 10% |
| Production | parentbased_traceidratio | 1% |