---

name: observability-and-extensions description: "Operate and extend Mellea 0.8 observability safely across plugins, hooks, logging, metrics, tracing, custom components, and contribution boundaries." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Mellea observability and extensions

Use this skill for Mellea 0.8.0.dev0 tasks involving plugins, hook ordering or scope, built-in debug plugins, logging, OpenTelemetry metrics or traces, generation usage metadata, custom components, extension packaging, or contribution-safe integration.

Route first

• Route construction of generative programs, requirements, sampling behavior, async execution, and workflow-local components to generative-programming. Return here when the task is instrumentation or a reusable extension.
• Route m serve, service processes, endpoint health, deployment configuration, and production CLI operations to serving-and-cli. This skill owns the library-side signal and exporter boundary, not deployment.
• Read only what the task needs:
  • plugin and hook API for registration, modes, priority, payload policy, lifecycle, scope, and debug plugins;
  • telemetry for logging, metrics, tracing, exporters, context, signal timing, and generation metadata;
  • extension patterns for custom components, plugins, backends, packaging, and contribution checks;
  • troubleshooting for missing dependencies, duplicate registration, stale configuration, missing signals, import cycles, and API drift.

Safe operating workflow

1. Establish the lifecycle owner and correlation key before choosing a hook. Decide whether the behavior observes, transforms, blocks, or records in the background.
2. Check the optional boundary without activating it. Run uv run python scripts/check_telemetry_install.py --require base; use hooks or telemetry only when that capability is required. The script forces all exporters and sinks off.
3. Choose the narrowest registration lifetime. Prefer plugin_scope(...), a scoped PluginSet, or start_session(..., plugins=[...]); use global register(...) only for process infrastructure with explicit teardown.
4. Use async def handlers. Set the execution mode and distinct priorities when behavior depends on order. Lower numbers run first within a mode, but mode phase precedes numeric priority and equal-priority order is unspecified.
5. Treat hook payloads as immutable. Return modify(payload, ...) only from a modifying mode and only for fields allowed by that hook's payload policy.
6. Open a span in a pre/start hook, correlate middle events by lifecycle id, and close on every success and error/end path. A completion-only hook can record a counter or histogram but cannot retrospectively anchor a span.
7. Keep signal setup at the application boundary. Set flags before importing Mellea, keep content capture off by default, and never configure an exporter, webhook, or file sink in library import code or an availability probe.
8. Test with typed payloads, precomputed thunks, fake backends, in-memory signal providers, and deterministic teardown before any provider-backed or collector-backed integration case.

Non-negotiable contracts

• cpex is optional and gates registration, payload construction, and plugin execution. OpenTelemetry is optional and gates telemetry providers. Base Mellea and custom components must remain usable without either dependency.
• Registration state and telemetry providers are process-global. A session-owned registration is primarily a teardown lifetime, not proof of concurrent-session dispatch isolation.
• Automatic tracing and metrics are hook-fired plugins. Do not add direct metric/span calls to core or backend paths when an existing lifecycle plugin owns that signal. The narrow exception is synchronous code that cannot safely fire a paired hook on the same task.
• Generation metadata must preserve generation.model and generation.provider; generation.usage is None when unavailable or an OpenAI-shaped mapping containing prompt_tokens, completion_tokens, and total_tokens. Streaming machinery owns streaming and ttfb_ms.
• Built-in generation debug plugins log prompt and response previews independently of MELLEA_TRACES_CONTENT. Treat debug logging as content disclosure and scope it deliberately.
• Do not depend on private registry/provider state in an extension. Private reset helpers are acceptable only in tightly controlled package tests and must be rechecked on version changes.

Completion report

Report the Mellea version, optional dependency status, signal flags read before import, plugin registration lifetime, hook modes and priorities, writable-field use, correlation and error closure, metadata assertions, exporter/content boundary, teardown, checks run, and any deferred backend or collector evidence.