OpenTelemetry Integrations¶

Hangar is the runtime governance layer for MCP servers. It is not an observability platform. Hangar exports governance telemetry -- enforcement decisions, MCP server lifecycle events, capability violations, and identity-aware audit trails -- through the OpenTelemetry (OTEL) interoperability contract. Partner backends visualize it.

Agent --> Hangar (governance) --> OTLP --> [OTEL Collector | OpenLIT | Langfuse | Grafana]

This page covers how to connect Hangar to each supported backend and what governance data flows through.

MCP Attribute Taxonomy¶

Every span, metric, and audit log emitted by Hangar carries MCP-specific attributes defined in src/mcp_hangar/observability/conventions.py. These attributes form a stable contract that partner backends consume without Hangar-specific plugins.

MCP Server attributes¶

Tool invocation attributes¶

Enforcement attributes¶

Audit attributes¶

Behavioral attributes¶

Caller attributes (identity propagation)¶

Cost attributes (FinOps)¶

Risk attributes (semantic analysis)¶

Attributes in the mcp.risk.* namespace carry detection rule match signals from the semantic analysis engine. The engine evaluates multi-step tool call sequences per agent session against detection rules (e.g. credential exfiltration, privilege escalation). Partner backends such as OpenLIT, Grafana, and SIEM tools can filter spans by mcp.risk.severity = critical to surface high-risk events.

Requires the ENTERPRISE license tier. The mcp.risk.score and mcp.risk.session_anomaly_score attributes are populated by the WeightedRiskScorer when behavioral profiling is active. The scorer aggregates signals from BehavioralDeviationDetected, DetectionRuleMatched, and CapabilityViolationDetected events with exponential time decay.

Health attributes¶

Prometheus metric names¶

OTEL Collector¶

The OTEL Collector is the recommended entry point for governance telemetry. It receives OTLP from Hangar and routes spans, metrics, and logs to any supported backend -- Prometheus, Jaeger, OpenLIT, Datadog, or a custom pipeline.

Example: examples/otel-collector/

Getting started¶

Set these environment variables before starting Hangar:

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_SERVICE_NAME=mcp-hangar
MCP_TRACING_ENABLED=true

Start the reference stack:

cd examples/otel-collector
docker-compose up

This starts:

The collector config (otel-collector-config.yaml) receives OTLP on both gRPC and HTTP, exports metrics to Prometheus, and prints spans and logs to console for debugging. Replace the logging exporter with your production backend.

What flows through the collector¶

• Traces: Tool invocation spans carrying mcp.server.id, mcp.tool.name, mcp.tool.status, and enforcement attributes.
• Logs: Audit log records for tool invocation events and MCP server state transitions, exported by OTLPAuditExporter.
• Metrics: Prometheus metrics scraped from Hangar's /metrics endpoint or forwarded through the collector's Prometheus exporter.

OpenLIT¶

OpenLIT provides a trace explorer, session analytics, and cost attribution UI. Hangar exports governance telemetry; OpenLIT visualizes it. They connect through the OTEL Collector -- Hangar does not send data directly to OpenLIT.

Example: examples/openlit/

Getting started¶

cd examples/openlit
docker-compose up

This starts Hangar, an OTEL Collector, and OpenLIT. Open the OpenLIT dashboard at http://localhost:3000.

Environment variables for Hangar (already set in the docker-compose):

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_SERVICE_NAME=mcp-hangar
MCP_TRACING_ENABLED=true

What governance data is visible in OpenLIT¶

In the OpenLIT trace explorer, filter on MCP governance attributes:

• By MCP server: mcp.server.id = "math-server"
• By tool: mcp.tool.name = "add"
• By user: mcp.user.id = "alice"
• By enforcement action: mcp.enforcement.action = "block"
• By violation type: mcp.enforcement.violation_type = "egress_undeclared"

MCP Server lifecycle events (COLD, INITIALIZING, READY, DEGRADED, DEAD) appear as audit log records with mcp.server.state attributes.

Langfuse¶

Langfuse provides LLM-specific observability: input/output recording, token counting, user session tracking, and evaluation workflows. It complements the OTEL governance telemetry path -- Langfuse handles LLM observability while OTEL handles governance observability.

• OTEL path: Enforcement decisions, capability violations, MCP server lifecycle, audit trails. Exported via OTLP to any OTEL-compatible backend.
• Langfuse path: Tool call input/output, token counts, user session traces. Exported via the LangfuseObservabilityAdapter.

Example: examples/langfuse/

Getting started¶

You need a running Langfuse instance -- either Langfuse Cloud or a self-hosted deployment.

Set these environment variables:

LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com   # or your self-hosted URL

Enable Langfuse in config.yaml:

observability:
  langfuse:
    enabled: true
    # Keys are read from environment variables
    # Never put secret keys in config files

How Hangar maps to Langfuse concepts¶

When Hangar propagates caller identity, Langfuse traces carry the same user_id and session_id as the MCP OTEL spans. This enables cross-referencing Langfuse traces with governance enforcement events in OTEL backends.

Grafana¶

Hangar exposes Prometheus metrics at the /metrics HTTP endpoint. Grafana can scrape these directly or consume them through the OTEL Collector's Prometheus exporter.

Pre-built Grafana dashboards are available in the monitoring/ directory:

• Overview dashboard: MCP server states, tool call rates, error rates
• MCP Server details dashboard: Per-MCP server metrics, health check history
• Alerts dashboard: Circuit breaker state, violation counts

Getting started¶

Start the monitoring stack:

cd monitoring
docker compose up -d

Start Hangar in HTTP mode so the /metrics endpoint is available:

mcp-hangar serve --http --port 8000

Key Prometheus queries¶

# Tool call rate per mcp_server (last 5 minutes)
rate(mcp_hangar_tool_calls_total[5m])

# 95th percentile tool call latency
histogram_quantile(0.95, rate(mcp_hangar_tool_call_duration_seconds_bucket[5m]))

# MCP servers currently in DEGRADED state (3=degraded)
mcp_hangar_mcp_server_state == 3

# Circuit breaker open count
mcp_hangar_circuit_breaker_state == 1

Integration stance¶

Hangar is not trying to become an observability platform. OpenTelemetry-compatible tools -- OpenLIT, Langfuse, Grafana, OTEL Collector, Datadog, Honeycomb -- are extensions to the visibility layer around Hangar. Hangar defines the governance telemetry contract (the MCP attribute taxonomy above) and exports it via OTEL. Partner tools consume, correlate, alert, and visualize.

This separation means:

• Hangar focuses on runtime security enforcement, lifecycle management, and governance policy.
• Partner tools focus on visualization, alerting, session analytics, and cost attribution.
• The OTEL interoperability contract ensures any OTEL-compatible tool works without Hangar-specific plugins.