structured logging

[kohlivrinda]

Summary

Adds first-class support for routing complexity classification data in request logs. When a governance routing rule references complexity_tier, the classifier now records the computed tier (SIMPLE, MEDIUM, COMPLEX), the raw score, and the mechanism used (lexical or skipped) into the BifrostContext. The logging plugin persists these values to three new database columns, and the HTTP API exposes them as filterable query parameters.

Changes

• Renamed BifrostContextKeyGovernanceRoutingMechanism to BifrostContextKeyGovernanceComplexityMechanism and AttrBifrostRoutingMechanism to AttrBifrostComplexityMechanism for consistency; added BifrostContextKeyGovernanceComplexityTier and BifrostContextKeyGovernanceComplexityScore context keys written by the governance plugin during routing rule evaluation.
• Introduced MechanismLexical and MechanismSkipped constants in the complexity package to standardise the mechanism values recorded in logs.
• The governance plugin now sets these context keys on all classification outcomes: successful lexical classification, unsupported input type, no signal detected, and analyzer-disabled-but-demanded paths all record an appropriate mechanism.
• Added a database migration (logs_add_complexity_routing_columns) that adds complexity_tier, complexity_mechanism, and complexity_score columns to the logs table, with partial indexes on the first two (skipping NULL rows since most requests will not use complexity routing).
• The logging plugin reads the three context keys in PostLLMHook and writes them to the log entry.
• SearchFilters gained ComplexityTiers and ComplexityMechanisms fields; applyFilters in the RDB store applies IN clauses for both; the materialized-view fast-path is bypassed when either filter is active.
• listSelectColumns now includes complexity_tier and complexity_mechanism so list responses carry these fields.
• HTTP handlers for getLogs, getLogsStats, and parseHistogramFilters parse complexity_tiers and complexity_mechanisms query parameters.
• OpenAPI spec updated with complexity_tiers and complexity_mechanisms query parameters on all three log endpoints, and complexity_tier, complexity_mechanism, and complexity_score response fields on the log object.
• Datadog connector documentation updated to describe the complexity_tier and complexity_mechanism tags, including example metric queries and a note that the raw score is not exported as a tag due to unbounded cardinality.
• Enrichment dimension routing_mechanism renamed to complexity_mechanism to match the updated attribute name.
• Parity tests extended with tier/mechanism/score fixtures and new complexity_tiers, complexity_mechanisms, and mechanism_skipped search cases.
• New unit tests cover: context values written on a successful lexical classification, no values written when no rule demands complexity, and skipped mechanism recorded when an unsupported input type is encountered. A logging plugin test verifies all three fields are persisted to the store.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

go test ./framework/logstore/... ./plugins/governance/... ./plugins/logging/...

• Send a chat completion request through a virtual key whose routing rules reference complexity_tier.
• Retrieve the log via GET /logs?complexity_tiers=COMPLEX and confirm complexity_tier, complexity_mechanism, and complexity_score are populated.
• Send an embedding request through the same routing rule and confirm the log shows complexity_mechanism: skipped with null tier and score.
• Filter by complexity_mechanisms=lexical and complexity_mechanisms=skipped to verify both filter paths return the expected subsets.

Breaking changes

• Yes
• No

The new columns are nullable and default to NULL for all existing rows. The migration is additive only. The rename from routing_mechanism to complexity_mechanism affects context keys, span attributes, Prometheus label names, and enrichment dimensions — consumers of those internal identifiers will need to update their references.

Security considerations

The complexity score and tier are derived from request content already visible to admins in the log detail view. No new PII is introduced. The raw score is stored as an unindexed float and is only returned in detail views.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[kohlivrinda]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• semantic router: incremental embedding + embed usage accounting #5896 : 2 dependent PRs (#5901 , #5924 )
• semantic router ui revamp #5865
• move complexity exemplars to configstore with backfill migration #5842
• feat(complexity): harness-aware complexity input extraction for cc and codex #5810
• server: export ObserveWarmupRoutingEmbedding for enterprise #5791
• weaviate + redis adapter fixes #5790
• semantic routing ui #5743
• semantic router: dimension probe + message history window #5748
• semantic cache: min similarity + fallback logging #5742
• smenatic router: budgeting+telemetry management #5686
• semantic routing #5: added semantic classifier for complexity router + handlers changes #5680
• semantic router #3: embedding executor #5656
• semantic router #2: semantic routing config #5655
• semantic router #1: add chromem backend #5628
• complexity : reducing keyword lists from 4 -> 3 lists #5602
• helm and docs changes #5530
• update complexity boundaries #5529
• expose tier/mechanism on every surface #5499
• structured logging #5497 👈 (View in Graphite)
• complexity tier merge #5494
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 47463c35-35db-492d-a641-8f1f43641364

📥 Commits

Reviewing files that changed from the base of the PR and between 956a451 and d094e49.

📒 Files selected for processing (19)

• core/schemas/bifrost.go
• core/schemas/enrichment.go
• core/schemas/trace.go
• docs/features/observability/datadog.mdx
• docs/openapi/openapi.json
• framework/logstore/logstoreparity_test.go
• framework/logstore/matviews.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/tables.go
• framework/tracing/tracer.go
• plugins/governance/complexity/config.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/routing.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• plugins/telemetry/main.go
• transports/bifrost-http/handlers/logging.go

🚧 Files skipped from review as they are similar to previous changes (13)

• plugins/logging/main.go
• core/schemas/trace.go
• docs/features/observability/datadog.mdx
• framework/logstore/matviews.go
• framework/tracing/tracer.go
• framework/logstore/tables.go
• transports/bifrost-http/handlers/logging.go
• plugins/logging/operations_test.go
• framework/logstore/logstoreparity_test.go
• plugins/governance/complexity/config.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• core/schemas/enrichment.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added governance complexity tier, mechanism, and optional score metadata to request logs, traces, and metrics.
  • Added complexity filters to log search, statistics, and histogram endpoints.
  • Added complexity fields and filtering options to the API, including tier and mechanism values.
• Bug Fixes
  • Records skipped when complexity classification is unavailable.
  • Applies complexity filters consistently and falls back from hourly summaries when needed.
• Documentation
  • Updated Datadog guidance for complexity tags and clarified that raw scores remain available only in logs.

Walkthrough

Governance complexity classification records tier, mechanism, and score in request context. The metadata flows into traces, metrics, persisted logs, and searchable APIs. Log APIs support complexity filters and response fields. Migrations, parity tests, OpenAPI schemas, and observability documentation cover the metadata.

Changes

Governance complexity observability

Layer / File(s)	Summary
Complexity context propagation core/schemas/bifrost.go, plugins/governance/complexity/config.go, plugins/governance/main.go, plugins/governance/routing.go, plugins/governance/prerequesthookcomplexity_test.go	Governance routing defines lexical and skipped mechanisms. Routing records tier and score for successful classification, or a skipped mechanism when analysis is unavailable. Tests verify these context states.
Trace, metric, and enrichment attribution core/schemas/trace.go, core/schemas/enrichment.go, framework/tracing/tracer.go, plugins/telemetry/main.go, docs/features/observability/datadog.mdx	Tracing, enrichment dimensions, and telemetry use complexity mechanism fields. Datadog documentation describes complexity tiers, mechanism states, and score availability.
Log persistence and enrichment framework/logstore/tables.go, framework/logstore/migrations.go, plugins/logging/main.go, plugins/logging/operations_test.go	Log storage adds nullable complexity tier, mechanism, and score fields. Migrations add the columns and partial indexes. Logging hooks persist context metadata. Tests verify persistence.
Log query and API contract framework/logstore/rdb.go, framework/logstore/matviews.go, transports/bifrost-http/handlers/logging.go, framework/logstore/logstoreparity_test.go, docs/openapi/openapi.json	Log queries and HTTP handlers support complexity filters. Materialized-view eligibility rejects these filters. OpenAPI schemas expose query parameters and response fields. Parity tests cover filtering and returned metadata.

Estimated code review effort: 4 (Complex) | ~60 minutes

Mergeability Score: 🔵 Low · up to d094e

The PR adds filterable complexity metadata, but the API schema still permits arbitrary non-null mechanism strings instead of enforcing the documented values. This is a bounded contract risk requiring owner awareness or a small follow-up; the change is otherwise mergeable.

Sequence Diagram(s)

sequenceDiagram
  participant GovernancePlugin
  participant BifrostContext
  participant PostLLMHook
  participant Logstore
  participant HTTPHandler
  GovernancePlugin->>BifrostContext: record complexity tier, mechanism, and score
  PostLLMHook->>BifrostContext: read complexity metadata
  PostLLMHook->>Logstore: persist enriched log entry
  HTTPHandler->>Logstore: query with complexity filters
  Logstore-->>HTTPHandler: return logs with complexity fields

Loading

Possibly related PRs

• maximhq/bifrost#5494: Both PRs modify governance complexity metadata and telemetry integrations.
• maximhq/bifrost#5499: Both PRs expose complexity fields and filters across log APIs.
• maximhq/bifrost#5530: Both PRs modify complexity metadata, filters, and OpenAPI logging schemas.

Suggested reviewers: akshaydeo, impoiler, danpiths

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title relates to logging but is too broad to identify the primary change: routing complexity data in request logs.	Use a specific title such as "Persist routing complexity metadata in request logs and API responses".

✅ Passed checks (3 passed)

Check name	Status	Explanation
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.
Description check	✅ Passed	The description covers the required sections, changes, testing, affected areas, breaking changes, security, and checklist with sufficient detail.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/structured-routing-logging

---

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.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

framework/logstore/matviews.go (1)

788-789: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add regression coverage for the new matview exclusions.

Line 788-789 correctly routes non-empty complexity and routing-mechanism filters to raw logs. Add deterministic cases for each filter, plus empty slices, so future changes cannot send unsupported filters to mv_logs_hourly and return incomplete results.

As per path instructions, framework changes should include tests that cover edge cases and failure paths.

🤖 Prompt for 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.

In `@framework/logstore/matviews.go` around lines 788 - 789, Add regression tests
around the matview-routing logic containing ComplexityTiers and
RoutingMechanisms, covering non-empty and empty slices for each filter. Assert
that populated unsupported filters route to raw logs rather than mv_logs_hourly,
while empty slices preserve the existing matview path; keep the cases
deterministic and include the relevant failure-path assertions.

Source: Path instructions

🤖 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 `@framework/logstore/logstoreparity_test.go`:
- Line 414: Update the parity projection in the logstore parity test to include
l.ComplexityScore alongside ComplexityTier and RoutingMechanism, ensuring lookup
comparisons verify the persisted complexity score.

In `@plugins/logging/main.go`:
- Around line 929-931: Update the fallback error-entry path used when
pendingLogsEntries is missing so it also persists complexityTier,
routingMechanism, and complexityScore metadata before writing and returning.
Reuse the values retrieved near the complexity metadata setup, including the
hasComplexityScore state, and preserve the existing metadata behavior for normal
entries.

---

Nitpick comments:
In `@framework/logstore/matviews.go`:
- Around line 788-789: Add regression tests around the matview-routing logic
containing ComplexityTiers and RoutingMechanisms, covering non-empty and empty
slices for each filter. Assert that populated unsupported filters route to raw
logs rather than mv_logs_hourly, while empty slices preserve the existing
matview path; keep the cases deterministic and include the relevant failure-path
assertions.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b9787ea-62e2-4cbb-91ac-bb0959066ae7

📥 Commits

Reviewing files that changed from the base of the PR and between 1b8e8ee and b4a90f3.

📒 Files selected for processing (14)

• core/schemas/bifrost.go
• docs/openapi/openapi.json
• framework/logstore/logstoreparity_test.go
• framework/logstore/matviews.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/tables.go
• plugins/governance/complexity/config.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/routing.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• transports/bifrost-http/handlers/logging.go

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/openapi/openapi.json`:
- Around line 82627-82645: Update the OpenAPI 3.1 schema definitions for
complexity_tier, routing_mechanism, and complexity_score to remove nullable and
represent null using JSON Schema null branches. Keep complexity_tier’s existing
enum values while adding null to its allowed values, and use anyOf with a null
type for the other nullable fields.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4f4a3b8f-7a0f-4c6e-884f-0737c549fd32

📥 Commits

Reviewing files that changed from the base of the PR and between b4a90f3 and a7be829.

📒 Files selected for processing (14)

• core/schemas/bifrost.go
• docs/openapi/openapi.json
• framework/logstore/logstoreparity_test.go
• framework/logstore/matviews.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/tables.go
• plugins/governance/complexity/config.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/routing.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• transports/bifrost-http/handlers/logging.go

🚧 Files skipped from review as they are similar to previous changes (12)

• plugins/governance/complexity/config.go
• framework/logstore/matviews.go
• framework/logstore/rdb.go
• plugins/governance/prerequesthookcomplexity_test.go
• transports/bifrost-http/handlers/logging.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• framework/logstore/tables.go
• plugins/governance/main.go
• plugins/governance/routing.go
• framework/logstore/migrations.go
• framework/logstore/logstoreparity_test.go

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@framework/logstore/migrations.go`:
- Line 283: Update the migration registry around
migrationAddComplexityRoutingColumns so idx_logs_complexity_tier and
idx_logs_complexity_mechanism are removed from logs_add_performance_indexes and
created by a new dedicated concurrent-index migration registered after the
column migration. Ensure fresh installs create the indexes only after the
columns exist, while existing deployments run the new migration.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a5d75543-8f1e-40f1-a973-24addb0f0ea6

📥 Commits

Reviewing files that changed from the base of the PR and between a7be829 and ac858a4.

📒 Files selected for processing (18)

• core/schemas/bifrost.go
• core/schemas/enrichment.go
• core/schemas/trace.go
• docs/openapi/openapi.json
• framework/logstore/logstoreparity_test.go
• framework/logstore/matviews.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/tables.go
• framework/tracing/tracer.go
• plugins/governance/complexity/config.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/routing.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• plugins/telemetry/main.go
• transports/bifrost-http/handlers/logging.go

🚧 Files skipped from review as they are similar to previous changes (9)

• framework/logstore/matviews.go
• plugins/governance/routing.go
• framework/logstore/tables.go
• framework/logstore/rdb.go
• plugins/logging/main.go
• plugins/governance/complexity/config.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/main.go
• framework/logstore/logstoreparity_test.go

[kohlivrinda]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[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 `@core/schemas/enrichment.go`:
- Around line 69-74: Update the Datadog connector documentation, especially the
Bifrost Context/tag section and related query guidance, to describe the new
complexity_tier and complexity_mechanism connector dimensions, including their
supported values and attribution usage. Do not document the raw complexity score
as a dimension.

In `@plugins/telemetry/main.go`:
- Line 275: The telemetry migration must remain additive: in
plugins/telemetry/main.go lines 275, 921, and 954-955, retain and populate the
legacy routing_mechanism label alongside complexity_mechanism; in
core/schemas/trace.go lines 799-799, preserve the deprecated routing-mechanism
attribute constant; in core/schemas/enrichment.go lines 75-76, retain the legacy
enrichment dimension; and in framework/tracing/tracer.go lines 358-359, emit the
legacy trace attribute alongside bifrost.complexity_mechanism.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a0b59628-4586-499c-8cff-a474369d12c2

📥 Commits

Reviewing files that changed from the base of the PR and between d700aae and ac858a4.

📒 Files selected for processing (18)

• core/schemas/bifrost.go
• core/schemas/enrichment.go
• core/schemas/trace.go
• docs/openapi/openapi.json
• framework/logstore/logstoreparity_test.go
• framework/logstore/matviews.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/tables.go
• framework/tracing/tracer.go
• plugins/governance/complexity/config.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/routing.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• plugins/telemetry/main.go
• transports/bifrost-http/handlers/logging.go

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@framework/logstore/migrations.go`:
- Around line 2708-2719: Remove idx_logs_complexity_tier and
idx_logs_complexity_mechanism from performanceIndexes, then add both partial
concurrent index definitions in a new migration step positioned after
logs_add_complexity_routing_columns. Ensure fresh installations create the
columns before these indexes, while existing installations execute the new
migration and receive both indexes.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9b03aacf-799e-4b61-93b8-db86e293d5b7

📥 Commits

Reviewing files that changed from the base of the PR and between 81bd30f and f55678d.

📒 Files selected for processing (19)

• core/schemas/bifrost.go
• core/schemas/enrichment.go
• core/schemas/trace.go
• docs/features/observability/datadog.mdx
• docs/openapi/openapi.json
• framework/logstore/logstoreparity_test.go
• framework/logstore/matviews.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/tables.go
• framework/tracing/tracer.go
• plugins/governance/complexity/config.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/routing.go
• plugins/logging/main.go
• plugins/logging/operations_test.go
• plugins/telemetry/main.go
• transports/bifrost-http/handlers/logging.go

🚧 Files skipped from review as they are similar to previous changes (15)

• plugins/governance/routing.go
• plugins/governance/prerequesthookcomplexity_test.go
• framework/logstore/matviews.go
• plugins/governance/complexity/config.go
• docs/features/observability/datadog.mdx
• framework/logstore/rdb.go
• framework/logstore/tables.go
• plugins/logging/operations_test.go
• framework/tracing/tracer.go
• core/schemas/trace.go
• plugins/governance/main.go
• framework/logstore/logstoreparity_test.go
• core/schemas/enrichment.go
• plugins/logging/main.go
• transports/bifrost-http/handlers/logging.go

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.