feat: add cluster-aware log metadata and per-node usage aggregation

[danpiths]

Summary

Add optional cluster metadata columns to the logs table and a per-node usage
aggregation query on the LogStore interface. These are foundational hooks for
improved governance accuracy in multi-node deployments.

Changes

• 3 new context keys for passing node ID and governance resource IDs through the
  request pipeline
• 3 new nullable columns on the Log struct: cluster_node_id, budget_ids,
  rate_limit_ids
• NodeUsageAggregate struct and GetNodeUsageSince method on the LogStore
  interface for aggregating a node's usage since a given timestamp
• Non-blocking migration: column additions are instant
  (ALTER TABLE ADD COLUMN), index built via CREATE INDEX CONCURRENTLY in a
  background goroutine
• Logging plugin gains SetClusterNodeID() setter and stamps entries with
  cluster metadata from the request context when set

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

make build LOCAL=1
make test-core
make test-plugins

Start with a fresh database and verify migration completes without errors. The
new columns are nullable and unused unless explicitly wired by the caller.

Screenshots/Recordings

N/A — no UI changes.

Breaking changes

• Yes
• No

New columns are nullable and optional. The GetNodeUsageSince method is
additive to the LogStore interface. Existing log entries are unaffected.

Related issues

N/A

Security considerations

No security implications. New columns store opaque IDs only.

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

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[danpiths]

• feat: add cluster-aware log metadata and per-node usage aggregation #3590 👈 (View in Graphite)
• 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51642caa-4e08-4aea-8ae4-fc47a436024b

📥 Commits

Reviewing files that changed from the base of the PR and between 76c4f27 and 3846895.

📒 Files selected for processing (7)

• core/schemas/bifrost.go
• framework/logstore/hybrid.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/store.go
• framework/logstore/tables.go
• plugins/logging/main.go

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

• framework/logstore/hybrid.go
• framework/logstore/store.go
• framework/logstore/rdb.go
• core/schemas/bifrost.go
• framework/logstore/tables.go
• plugins/logging/main.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Cluster node identification and attribution for multi-node deployments
  • Governance budget and rate-limit ID tracking attached to logs for observability
  • Query per-node usage metrics (cost, tokens, successful requests) over a time range
• Chores
  • Database migration and index added to persist and index cluster/governance fields for logs

Walkthrough

This PR adds cluster node identification and governance metadata support to logging: new context keys, Log model persistence and JSON (de)serialization for budget/rate-limit IDs, DB migration and partial index, a LogStore.GetNodeUsageSince implementation and delegation, and plugin wiring to attach context-derived fields to log entries.

Changes

Cluster Governance and Node Usage

Layer / File(s)	Summary
Context keys, Log model extension, and aggregate type core/schemas/bifrost.go, framework/logstore/tables.go	Adds BifrostContextKeyClusterNodeID, BifrostContextKeyGovernanceBudgetIDs, BifrostContextKeyGovernanceRateLimitIDs. Extends Log with ClusterNodeID, BudgetIDs, RateLimitIDs storage fields and BudgetIDsParsed, RateLimitIDsParsed virtual fields. Adds exported NodeUsageAggregate type.
LogStore interface framework/logstore/store.go	Adds GetNodeUsageSince(ctx, nodeID, since) (*NodeUsageAggregate, error) to the LogStore interface with comments describing node-scoped cumulative usage.
Serialization, deserialization, and database migration framework/logstore/tables.go, framework/logstore/migrations.go	Log.SerializeFields marshals parsed governance ID slices into pointer string fields when non-empty; Log.DeserializeFields unmarshals stored strings back into parsed slices (sets to nil on unmarshal error). Migration migrationAddClusterGovernanceColumns conditionally adds cluster_node_id, budget_ids, rate_limit_ids to logs with rollback; performanceIndexes adds concurrent partial index idx_logs_cluster_node_id.
RDB log store query implementation framework/logstore/rdb.go	RDBLogStore.GetNodeUsageSince queries successful logs for a cluster_node_id since a timestamp, selects cost/total_tokens and stored governance ID strings, unmarshals per-row governance IDs where possible, deduplicates IDs, attributes cost to each budget ID, and aggregates request/token counts per rate-limit ID into NodeUsageAggregate.
Store abstraction, hybrid delegation, and logging plugin integration framework/logstore/hybrid.go, plugins/logging/main.go	HybridLogStore.GetNodeUsageSince delegates to the wrapped inner store. LoggerPlugin gains clusterNodeID atomic storage and SetClusterNodeID. PostLLMHook sets entry.ClusterNodeID when available and reads BifrostContextKeyGovernanceBudgetIDs / BifrostContextKeyGovernanceRateLimitIDs from context to populate entry.BudgetIDsParsed and entry.RateLimitIDsParsed.

Sequence Diagram(s)

sequenceDiagram
  participant LoggerPlugin
  participant HybridLogStore
  participant RDBLogStore
  participant Postgres
  LoggerPlugin->>HybridLogStore: persist log entry (ClusterNodeID, BudgetIDsParsed, RateLimitIDsParsed)
  HybridLogStore->>RDBLogStore: delegate persistence / GetNodeUsageSince calls
  RDBLogStore->>Postgres: SELECT cost,total_tokens,budget_ids,rate_limit_ids WHERE cluster_node_id=... AND timestamp>=...
  Postgres->>RDBLogStore: return rows
  RDBLogStore->>RDBLogStore: parse JSON, dedupe IDs, aggregate into NodeUsageAggregate

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• roroghost17

Poem

🐰 I stitched node IDs into the logs,
With budgets like tiny cogs,
Tokens counted in rows,
Across nodes the data flows,
Hop — governance hums in soft bogs.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add cluster-aware log metadata and per-node usage aggregation' accurately captures the main changes: introduction of cluster metadata columns and per-node usage aggregation functionality.
Description check	✅ Passed	The PR description comprehensively addresses all key template sections: summary explains the purpose, changes details modifications with design decisions, type and affected areas are marked, testing steps are provided, breaking changes clearly marked as 'No', and security considerations documented.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 05-19-feat_add_cluster-aware_log_metadata_and_per-node_usage_aggregation

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

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

[greptile-apps]

Confidence Score: 5/5

Safe to merge — all new columns are nullable, the migration is non-blocking, and the aggregation query is additive to the interface.

The change is well-scoped: columns default to NULL, no existing log entries are touched, and the new interface method is implemented consistently across RDBLogStore and HybridLogStore. The concurrency concerns raised in prior review rounds have been addressed. The only outstanding observation is a minor metadata asymmetry in the error fallback path that does not affect the core aggregation logic.

No files require special attention.

Important Files Changed

Filename	Overview
core/schemas/bifrost.go	Adds 3 new context key constants for cluster node ID and governance resource IDs; straightforward and non-breaking.
framework/logstore/hybrid.go	Adds GetNodeUsageSince delegation to the inner store; consistent with all other delegated methods in HybridLogStore.
framework/logstore/migrations.go	Adds transactional column migration for cluster governance columns and a composite partial index on (cluster_node_id, timestamp); index is built via CONCURRENTLY outside the transaction boundary.
framework/logstore/rdb.go	Implements GetNodeUsageSince with per-ID deduplication, warn-logged unmarshal errors, and correct status = 'success' filtering; clean implementation.
framework/logstore/store.go	Adds GetNodeUsageSince to the LogStore interface with a clear doc comment.
framework/logstore/tables.go	Adds nullable cluster governance fields to the Log struct with matching Parsed counterparts, serialization/deserialization, and the NodeUsageAggregate type.
plugins/logging/main.go	Adds SetClusterNodeID using atomic.Value, stamps cluster metadata in the main PostLLMHook success path; error fallback path sets node ID but omits governance IDs.

_{Reviews (3): Last reviewed commit: "feat: add cluster-aware log metadata and..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

framework/logstore/migrations.go (1)

2466-2470: ⚡ Quick win

Mirror this index on the SQLite migration path.

idx_logs_cluster_node_id is only being added through the PostgreSQL-only performanceIndexes background path. GetNodeUsageSince was added on RDBLogStore for the shared logstore implementation, so SQLite will still full-scan logs for that new query unless the non-Postgres migration path also creates an equivalent index.

Based on learnings only PostgreSQL and SQLite database dialects are supported in framework/logstore.

🤖 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/migrations.go` around lines 2466 - 2470, Add the same
index for SQLite so GetNodeUsageSince on RDBLogStore won’t full-scan: in
framework/logstore/migrations.go, locate the SQLite migration path (the
migrations array used for the non-Postgres path) and add an entry mirroring
idx_logs_cluster_node_id (use the SQLite-compatible CREATE INDEX statement for
idx_logs_cluster_node_id on logs(cluster_node_id), handling SQLite partial-index
syntax if needed). Ensure the new migration entry is named
"idx_logs_cluster_node_id" and aligns with the existing migration pattern so it
runs for SQLite alongside performanceIndexes for Postgres.

🤖 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/rdb.go`:
- Around line 371-389: The loop that attributes row.Cost and row.TotalTokens
uses budgetIDs and rateLimitIDs directly after sonic.Unmarshal, which
double-counts when the decoded slices contain duplicates; update the handling in
the blocks that read row.BudgetIDs and row.RateLimitIDs to normalize each
decoded slice to unique IDs (e.g., build a temporary map[string]struct{} set
from budgetIDs and rateLimitIDs) and then iterate the set keys to increment
budgetCosts[id] += row.Cost, rateLimitRequests[id]++, and rateLimitTokens[id] +=
row.TotalTokens only once per unique id.
- Around line 346-359: The query scans nullable numeric columns into
non-nullable fields: update the SELECT in the s.db...Model(&Log{}) query (the
call that builds and executes the Find into []logRow) to use COALESCE for
numeric nullable columns, e.g. COALESCE(cost, 0) AS cost and
COALESCE(total_tokens, 0) AS total_tokens so the logRow struct can safely
receive defaults when DB values are NULL; keep budget_ids and rate_limit_ids
as-is.

In `@plugins/logging/main.go`:
- Around line 354-359: SetClusterNodeID currently writes p.clusterNodeID without
synchronization while PostLLMHook reads it concurrently, causing a race; either
(A) protect the write and all reads with the existing mutex p.mu by acquiring
p.mu.Lock()/Unlock() in SetClusterNodeID and reading p.clusterNodeID under p.mu
in PostLLMHook, or (B) change p.clusterNodeID to an atomic.Value and use
Store/Load there and in PostLLMHook; update comments to state the chosen
approach and ensure all accesses to p.clusterNodeID (SetClusterNodeID and
PostLLMHook) follow the same synchronization strategy.

---

Nitpick comments:
In `@framework/logstore/migrations.go`:
- Around line 2466-2470: Add the same index for SQLite so GetNodeUsageSince on
RDBLogStore won’t full-scan: in framework/logstore/migrations.go, locate the
SQLite migration path (the migrations array used for the non-Postgres path) and
add an entry mirroring idx_logs_cluster_node_id (use the SQLite-compatible
CREATE INDEX statement for idx_logs_cluster_node_id on logs(cluster_node_id),
handling SQLite partial-index syntax if needed). Ensure the new migration entry
is named "idx_logs_cluster_node_id" and aligns with the existing migration
pattern so it runs for SQLite alongside performanceIndexes for Postgres.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9ad6fdf3-a779-4d15-80ee-26e556ed0dcd

📥 Commits

Reviewing files that changed from the base of the PR and between 4a42d35 and 7b9b16d.

📒 Files selected for processing (7)

• core/schemas/bifrost.go
• framework/logstore/hybrid.go
• framework/logstore/migrations.go
• framework/logstore/rdb.go
• framework/logstore/store.go
• framework/logstore/tables.go
• plugins/logging/main.go

[akshaydeo]

Merge activity

• May 19, 12:40 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 19, 12:40 PM UTC: @akshaydeo merged this pull request with Graphite.