Skip to content

Add event_tags and event_properties callbacks#29

Open
kashishhora wants to merge 1 commit intomainfrom
feat/event-tags-properties
Open

Add event_tags and event_properties callbacks#29
kashishhora wants to merge 1 commit intomainfrom
feat/event-tags-properties

Conversation

@kashishhora
Copy link
Copy Markdown
Member

@kashishhora kashishhora commented Apr 19, 2026

What

Two new callbacks on MCPCatOptionsevent_tags and event_properties — that let customers attach custom metadata to every auto-captured event (initialize, tools/list, tools/call). Ports the equivalent feature from the TypeScript SDK (PR #32 there).

  • event_tags: dict[str, str], validated client-side (regex on keys, length caps, max 50 entries, no newlines in values). Invalid entries are dropped with a warning.
  • event_properties: dict[str, Any], arbitrary JSON-serializable metadata, no validation.
  • Both bypass redaction/sanitization/truncation — customer-supplied, passed through as-is.
  • Both accept sync or async callables.

Why

Customers want to filter/group events by structured metadata they control — trace IDs, environments, deployment regions, feature flags. Until now there's no way to attach that kind of data through the SDK.

Exporter changes worth flagging

  • Every outbound event now carries source=mcpcat (new MCPCAT_SOURCE constant). Makes MCPcat events distinguishable from other telemetry flowing into the customer's observability backend.
  • Customer tags are namespaced — mcpcat.<key> in Datadog ddtags and Sentry tags, mcpcat.tag.<key> as OTLP span attributes. Prevents collisions with reserved tag keys (environment, release, host, service, etc.).
  • Sentry properties moved from the deprecated extra field into contexts.mcpcat.

Test plan

  • uv run python -m pytest tests/test_event_tags_properties.py tests/test_tag_validation.py -v — 34 tests pass
  • uv run python -m pytest — full regression green
  • Manually verified end-to-end against local BE: SDK sends events with tags/properties → SQS → process_events → event detail API returns them. Confirmed for both sync and async callback paths. Covered in the separate BE change that exposes tags/properties on EventSerializer.

Notes

  • Async callback support uses the same sync-or-async pattern as RedactionFunction. If the callback returns a coroutine, the resolver awaits it; otherwise passes through.
  • Validation rules match the TS SDK and the backend's validate_tags exactly, so client- and server-side drop behavior is consistent.
  • identify remains sync-only for now — making it async-compatible is a separate (small) change.

Port the event tags & properties feature from the TypeScript SDK. Two new
callbacks on MCPCatOptions attach customer-defined metadata to every
auto-captured event (initialize, tools/list, tools/call):

- event_tags: dict[str, str], validated client-side (max 50 entries, key
  regex [a-zA-Z0-9$_.:\- ] <=32 chars, value <=200 chars, no newlines).
  Invalid entries dropped with warning.
- event_properties: dict[str, Any], flexible JSON, no validation.

Both fields are top-level on the published event and bypass the
redaction/sanitization/truncation pipeline. Callbacks accept sync or
async callables; async results are awaited transparently.

Exporter updates:
- Every outbound event now carries source=mcpcat (via new MCPCAT_SOURCE
  constant) so consumers can filter by provenance.
- Customer tags are namespaced under mcpcat.* in Datadog ddtags, Sentry
  tags, and as mcpcat.tag.* OTLP span attributes to avoid collisions
  with each platform's reserved tag keys.
- Sentry properties moved from deprecated `extra` into a `contexts.mcpcat`
  entry via a new build_contexts() helper.
@kashishhora kashishhora requested a review from naji247 April 19, 2026 21:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant