observability-and-extensions
Operate and extend Mellea 0.8 observability safely across plugins, hooks, logging, metrics, tracing, custom components, and contribution boundaries.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- observability-and-extensions
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Operate and extend Mellea 0.8 observability safely across plugins, hooks, logging, metrics, tracing, custom components, and contribution boundaries.
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/extension-patterns.md12.7 KB
- 参考文档references/plugin-and-hook-api.md12.7 KB
- 参考文档references/telemetry.md15.0 KB
- 参考文档references/troubleshooting.md15.1 KB
03 SKILL.md 正文
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 toserving-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
- Establish the lifecycle owner and correlation key before choosing a hook. Decide whether the behavior observes, transforms, blocks, or records in the background.
- Check the optional boundary without activating it. Run
uv run python scripts/check_telemetry_install.py --require base; usehooksortelemetryonly when that capability is required. The script forces all exporters and sinks off. - Choose the narrowest registration lifetime. Prefer
plugin_scope(...), a scopedPluginSet, orstart_session(..., plugins=[...]); use globalregister(...)only for process infrastructure with explicit teardown. - Use
async defhandlers. 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. - Treat hook payloads as immutable. Return
modify(payload, ...)only from a modifying mode and only for fields allowed by that hook's payload policy. - 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.
- 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.
- 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
cpexis 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.modelandgeneration.provider;generation.usageisNonewhen unavailable or an OpenAI-shaped mapping containingprompt_tokens,completion_tokens, andtotal_tokens. Streaming machinery ownsstreamingandttfb_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.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.