MATIH Platform is in active MVP development. Documentation reflects current implementation status.
19. Observability & Operations
OpenTelemetry Setup

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-otlp

Configuration

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-plane

OTel 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

VariableDescriptionDefault
OTEL_EXPORTER_OTLP_ENDPOINTOTel Collector endpointhttp://otel-collector:4317
OTEL_SERVICE_NAMEService name for tracesService-specific
OTEL_TRACES_SAMPLERSampling strategyparentbased_always_on
OTEL_TRACES_SAMPLER_ARGSampling rate1.0

Sampling Strategy

EnvironmentStrategyRate
Developmentalways_on100%
Stagingparentbased_traceidratio10%
Productionparentbased_traceidratio1%