kestrel-feature-observability

Lifecycle event observability for Kestrel Sovereign agents. Attaches an ObservabilityHook to the agent's hook system; every lifecycle event is logged to the agent's observability_store. Prometheus metrics emit through the SDK's shared registry, so a single /metrics scrape stays coherent across the framework + every feature package.

Installation

uv pip install kestrel-feature-observability

For real Prometheus output:

uv pip install 'kestrel-feature-observability[metrics]'

The feature is auto-discovered by Kestrel Sovereign via the kestrel_sovereign.features entry point — install it alongside kestrel-sovereign and ObservabilityFeature registers itself at startup.

Tools

Tool Category Description
observability_summary DATA_ACCESS Recent metric and error counts
observability_query DATA_ACCESS Query lifecycle events by type and time window
observability_session DATA_ACCESS Per-session event timeline

Console panels

The feature contributes two ES modules to the Console via get_ui_contributions(), each self-registering through the host ui-ext registerPanel registry and gated on the observability capability:

  • LLM Calls (static/llm-calls.js) — paged, filterable LLM-call table.
  • Fleet Timeline (static/timeline.js) — the headline swimlane view. A left agent selector populated from GET /agent-tree, and a right timeline of lanes (per agent) + nested sublanes — talon jobs / subagents indented under their driver via the event lineage fields (parent_agent/driven_by/ parent_session_id/subagent_id). Pause/Play, time-range (1m/5m/all), and status/tool/hook color modes; live updates via SSE when the host exposes an event stream, else polling of the subtree events endpoint.

static/timeline.js keeps its grouping logic (buildLanes/nestLanes) pure and DOM-free at import time — panel registration and rendering run only in a browser — so the nesting logic is unit-tested with node's built-in runner (node --test tests/timeline.nesting.test.mjs), ported from the original kestrel-claws dashboard/tests/timeline.test.ts. This swimlane supersedes the kestrel-claws dashboard/src/views/timeline.ts, which should be retired (removed or stubbed to point here) in a follow-up kestrel-claws PR.

Privacy

The hook is observational — it never blocks, denies, or modifies. User-message content is not logged (only length); tool errors are truncated to 200 chars; exceptions in the hook are swallowed so they cannot affect agent operation.

Dependencies

  • kestrel-sovereign-sdk>=0.14.1,<1 — base Feature, tool, ToolCategory, Hook, and shared metrics module
  • Optional [metrics] extra → kestrel-sovereign-sdk[metrics] → prometheus-client

No runtime dependency on kestrel-sovereign itself; the feature accesses agent.observability_store via duck typing, so it works against any host that provides one.

Development

uv pip install -e '.[test]'
uv run pytest

License

Apache-2.0

Project links

Data verified by PyPI on Jul 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.17.13)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for unclesaurus from gravatar.com unclesaurus

Credits

Author/Maintainer: UncleSaurus

GitHub Statistics

Data verified by PyPI on Jul 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python <3.15, >=3.11

Provides Extra

metrics test

Tags

agents ai kestrel metrics observability prometheus

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kestrel_feature_observability-0.4.0.tar.gz (32.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

kestrel_feature_observability-0.4.0-py3-none-any.whl (37.0 kB view details)

Uploaded Python 3

File details

Details for the file kestrel_feature_observability-0.4.0.tar.gz.

File metadata

File hashes

Hashes for kestrel_feature_observability-0.4.0.tar.gz
Algorithm Hash digest
SHA256 b09744e95fccbdd28b94e7f62c41e49cde7d1051e57f07681875d9f460ff8599
MD5 e0b7aa01351bd6db04c53ccfc9bb6d3f
BLAKE2b-256 6260c9834d53e5304f29cf1a8966dfd6cbb4852e2df97289d61dd4b2e1741d84

See more details on using hashes here.

Provenance

The following attestation bundles were made for kestrel_feature_observability-0.4.0.tar.gz:

Publisher: publish.yml on KestrelSovereignAI/kestrel-feature-observability

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kestrel_feature_observability-0.4.0-py3-none-any.whl.

File metadata

File hashes

Hashes for kestrel_feature_observability-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 40cecbf3ff170a0a6d823aebb994baad0b5b2e598f26a0e4c845e1f613bb925f
MD5 12d4dc1380854da20daaaece91b8be7c
BLAKE2b-256 8ed279b77ee3529f73d48b5555af88a47e52f57e54dd2d4cabbcb0acd2c3bc5d

See more details on using hashes here.

Provenance

The following attestation bundles were made for kestrel_feature_observability-0.4.0-py3-none-any.whl:

Publisher: publish.yml on KestrelSovereignAI/kestrel-feature-observability

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.17.13

2 files

0.17.12

2 files

0.17.11

2 files

0.17.10

2 files

0.17.9

2 files

0.17.8

2 files

0.17.7

2 files

0.17.6

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.1

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.0

2 files

0.10.0

2 files

0.9.0

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

This release

0.4.0 This release

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page