---

name: observability-integrations description: "Configure mcp-agent logging, OpenTelemetry tracing, token accounting, streaming, provider extras, local OpenAI-compatible providers, and LangChain/CrewAI tool adapters." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

observability-integrations

Use this sub-skill when a task involves mcp-agent observability or optional ecosystem integrations: structured logger transports, OpenTelemetry exporters, usage telemetry, token counters, progress displays, streaming callbacks, provider-specific extras, local OpenAI-compatible endpoints, LangChain tools, or CrewAI tools.

Start Here

1. Read references/logging-and-tracing.md for logger transport configuration, OTEL exporter syntax, trace helpers, token accounting, progress displays, streaming events, and safe event-log inspection.
2. Read references/provider-integrations.md for optional provider extras, import-vs-credential failures, model selector knobs, LM Studio/local OpenAI-compatible endpoints, and LangChain/CrewAI wrappers.
3. Read references/troubleshooting.md when config validation, OTEL export, JSONL logs, token counters, progress output, streaming, provider imports, adapters, or local model endpoints fail.
4. Run python scripts/check_observability_config.py --help before editing config; use --config mcp_agent.config.yaml --secrets mcp_agent.secrets.yaml --json for credential-redacted diagnostics.
5. Run python scripts/summarize_event_log.py --help and then point it at a small JSONL event log to validate file transport output without replaying interactive progress UI.

Core Workflows

• Enable structured logging with logger.transports, logger.level, logger.progress_display, and optional file/HTTP settings; prefer file plus console for local debugging and add HTTP only when an endpoint is intentionally configured.
• Enable tracing with otel.enabled: true, otel.service_name, otel.sample_rate, and one or more exporters: console, file, or otlp with endpoint and optional headers.
• Correlate logs and traces by running inside MCPApp.run() and using app.logger, running_app.context.logger, or agent.logger; active spans inject trace_id and span_id into events.
• Inspect token usage through the app or agent context token counter after AugmentedLLM calls; use progress display only for interactive TTY runs and use logs or summaries in CI.
• Treat provider SDKs and tool ecosystems as optional extras: import the relevant AugmentedLLM/tool adapter only after installing the matching extra and configuring non-secret model defaults.
• For streaming, consume generate_stream() events by type and keep callbacks non-blocking; use generate_str_stream() only when text deltas are enough.

Route Elsewhere

• Use ../core-sdk/SKILL.md for MCPApp, Agent, Settings, config/secrets basics, RequestParams fundamentals, local tool decorators, and normal provider setup.
• Use ../cli-cloud-operations/SKILL.md for cloud log tailing, cloud logger commands, deployment diagnostics, app/server status, and CLI authentication.
• Use ../mcp-server-integration/SKILL.md for MCP auth internals, server creation, transport semantics, upstream session lifecycle, and app-as-server behavior.
• Use ../workflow-patterns/SKILL.md for routers, orchestrators, parallel workflows, evaluator loops, and durable workflow composition.

Bundled Helpers

python scripts/check_observability_config.py --config mcp_agent.config.yaml --json
python scripts/summarize_event_log.py logs/mcp-agent.jsonl --limit 50 --json

Both helpers are self-contained and credential-safe. They do not import provider SDKs, contact external collectors, replay interactive displays, or require the original source repository.