[delete-cloud]

Summary

• Add provider-neutral agentkit observability primitives
• Add SpanRecord, ObservationEvent, ObservationSink, NoopObservationSink, and record_span
• Keep the core dependency-free and no-op by default
• Cover success spans, error spans with re-raise, sink fail-open behavior, error truncation, and attribute copying

Verification

• uv run pytest tests/agentkit/observability/test_core.py tests/agentkit/test_public_exports.py -q
• uv run basedpyright --level error src/agentkit/observability tests/agentkit/observability
• uv run ruff format --check src/agentkit/observability tests/agentkit/observability
• uv run ruff check src/agentkit/observability tests/agentkit/observability
• git diff --check

Summary by CodeRabbit

• New Features
  • Added observability framework with span recording, event tracking, and error capture capabilities.
  • Introduced provider-neutral observation sink interface for integration with monitoring systems.
  • Added no-operation sink implementation for systems without external monitoring configured.
  • Comprehensive test coverage for observability functionality.

[coderabbitai]

Warning

Rate limit exceeded

@delete-cloud has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 56 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 692ac2fb-a663-41d3-b0cf-fc3bb04d6e00

📥 Commits

Reviewing files that changed from the base of the PR and between abb6d2c and c67ade5.

📒 Files selected for processing (5)

• coding-agent/src/agentkit/observability/__init__.py
• coding-agent/src/agentkit/observability/models.py
• coding-agent/src/agentkit/observability/sinks.py
• coding-agent/src/agentkit/observability/spans.py
• coding-agent/tests/agentkit/observability/test_core.py

📝 Walkthrough

Walkthrough

This PR introduces a provider-neutral observability infrastructure for agentkit. It defines immutable domain models for observations, a pluggable sink protocol for recording, a record_span context manager for automatic instrumentation, and comprehensive tests validating attribute copying, error capture, message truncation, and sink resilience.

Changes

Observability Infrastructure

Layer / File(s)	Summary
Domain models for observations coding-agent/src/agentkit/observability/models.py	Type aliases ObservationStatus and ObservationAttributes; frozen dataclasses ObservationEvent (with auto-timestamp and attribute copying) and SpanRecord (with status, error metadata, duration tracking).
Observation sink protocol and noop implementation coding-agent/src/agentkit/observability/sinks.py	ObservationSink protocol defines record_span(span) and record_event(event) methods; NoopObservationSink provides a no-op implementation that drops all observations.
Span recording context manager and utilities coding-agent/src/agentkit/observability/spans.py	ActiveSpan dataclass holds mutable span attributes; record_span context manager measures execution time, captures exceptions with truncated error metadata, delegates to configurable sink (defaults to noop), and swallows sink failures.
Test coverage for observability primitives coding-agent/tests/agentkit/observability/test_core.py	Test helpers InMemoryObservationSink and FailingObservationSink; tests verify attribute immutability, exception handling with error type/message capture, 500-character error message truncation, sink failure resilience, and noop behavior.
Public API surface exports coding-agent/src/agentkit/observability/__init__.py	Package initializer re-exports ActiveSpan, ObservationAttributes, ObservationEvent, ObservationSink, ObservationStatus, SpanRecord, record_span, and NoopObservationSink via __all__.

Sequence Diagram(s)

sequenceDiagram
  participant Code as Business Logic
  participant RecordSpan as record_span Context
  participant ActiveSpan as ActiveSpan
  participant Sink as ObservationSink
  Code->>RecordSpan: enter context (with name, attributes)
  RecordSpan->>RecordSpan: start timer
  RecordSpan->>ActiveSpan: create with name, copied attributes
  RecordSpan->>Code: yield ActiveSpan
  Code->>ActiveSpan: set_attribute(key, value)
  Code->>RecordSpan: success or exception
  alt Success
    RecordSpan->>RecordSpan: compute duration_ms
    RecordSpan->>RecordSpan: create SpanRecord(status="ok")
  else Exception
    RecordSpan->>RecordSpan: capture error_type, error_message (truncated)
    RecordSpan->>RecordSpan: create SpanRecord(status="error")
  end
  RecordSpan->>Sink: record_span(SpanRecord)
  Sink->>Sink: record or drop
  RecordSpan->>Code: re-raise if exception

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A humble rabbit hops with glee,
to trace the paths that code will be!
With spans recorded, errors caught,
observability flows through ought;
The sink sits still, the records fly,
instrumentation reaches high! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.76% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add agentkit observability core' directly and accurately summarizes the main objective of adding core observability primitives to the agentkit package.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agentkit-observability-core

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@coding-agent/src/agentkit/observability/spans.py`:
- Around line 29-32: The bare except in the try/except around
sink.record_span(span) is intentional (fail-open for observability) but raises
ruff BLE001; update the except clause in spans.py to include an inline comment
"noqa: BLE001" and a short note like "intentional bare except to prevent sink
failures from impacting business logic" so the warning is suppressed and the
intent is documented (target the try/except that calls sink.record_span(span)).

In `@coding-agent/tests/agentkit/observability/test_core.py`:
- Line 78: The pytest.raises call uses a normal string for the regex pattern;
update the call to pass a raw string literal for the match parameter (replace
match="x+" with match=r"x+"), i.e., edit the pytest.raises(...) expression so
the regex is written as r"x+" to satisfy RUF043 and ensure the pattern is
interpreted correctly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 82b6b7b1-4ff2-4bba-a821-a8e004c6d2c5

📥 Commits

Reviewing files that changed from the base of the PR and between 1bb973d and abb6d2c.

📒 Files selected for processing (5)

• coding-agent/src/agentkit/observability/__init__.py
• coding-agent/src/agentkit/observability/models.py
• coding-agent/src/agentkit/observability/sinks.py
• coding-agent/src/agentkit/observability/spans.py
• coding-agent/tests/agentkit/observability/test_core.py