Skip to content

feat(ledger): add accounting diagnostics and balance telemetry - #5304

Open
GAlexIHU wants to merge 4 commits into
codex/billing-collection-booking-timefrom
codex/ledger-error-telemetry
Open

GAlexIHU wants to merge 4 commits into
codex/billing-collection-booking-timefrom
codex/ledger-error-telemetry

Conversation

@GAlexIHU

@GAlexIHU GAlexIHU commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Negative FBO source minima emit a counter and diagnostic warning on every observation, including repeated reads. Logs include the source, query boundary, and minimum balance; the counter measures observations, not distinct failures.

Ledger accounting guards gain stable codes and reasons, surfaced by the shared error logger through wrapped and joined errors. Diagnostic traversal is bounded.

Introduce models.Error with the existing structured-error capabilities while keeping models.ValidationIssue a distinct type. Both share the implementation and preserve cause traversal and identity through context enrichment. Billing propagates structured system failures instead of storing them as validation issues, even when their cause is a validation issue.

Validation on the rebased stack: model, logging, HTTP, billing classification, PostgreSQL-backed ledger, and invoice error-propagation tests plus scoped Go lint passed.

Stack: #5252 → #5270 → #5294 → #5304. Depends on #5294.

Summary by CodeRabbit

  • New Features

    • Added structured system errors with diagnostic codes, severity, and contextual details.
    • Error logs now include diagnostic codes and reasons when available.
    • Negative credit balances are excluded from spendable credit and reported through warnings and metrics.
  • Improvements

    • Accounting and billing failures now provide consistent diagnostic reasons.
    • System errors remain distinct from validation issues unless explicitly converted.
  • Documentation

    • Clarified how system errors, validation issues, and accounting diagnostics are handled.

RetriggerView in GreptileConfidence Score: 5/5

This PR appears safe to merge; no new actionable issues remain.

Summary

Adds ledger error codes and reasons, includes them in shared error logs, and counts each observed negative FBO source balance.

  • Structured system errors stay separate from billing validation issues.
  • Ledger accounting guards name the reason each operation fails.
  • Shared error logs include codes and reasons from wrapped errors.
  • Negative FBO source balances now produce warnings and observations.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Ledger guard fails] --> B[models.Error with code and reason]
  B --> C[Shared error logger]
  C --> D[Log codes and reasons]
  B --> E{Explicit validation conversion?}
  E -->|No| F[Return operation failure]
  E -->|Yes| G[Create billing validation issue]
Loading

Reviews (5) · Last reviewed commit: "refactor(ledger): name diagnostic error ..." · Reviewed by Greptile

@GAlexIHU
GAlexIHU requested a review from a team as a code owner October 16, 2026 13:17
@GAlexIHU GAlexIHU added the release-note/misc Miscellaneous changes label Oct 16, 2026
@coderabbitai

coderabbitai Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository: openmeterio/openmeter/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3dd2d181-d510-49dd-86ea-bf68b0cb696d
📥 Commits

Reviewing files that changed from the base of the PR and between bea52da and 299ba20.

📒 Files selected for processing: 16
  • openmeter/billing/README.md
  • openmeter/billing/validationissue.go
  • openmeter/ledger/advance/service/attribution.go
  • openmeter/ledger/advance/service/legacy_correction.go
  • openmeter/ledger/breakage/breakage_impacts.go
  • openmeter/ledger/breakage/service.go
  • openmeter/ledger/collector/correction/legacy_references.go
  • openmeter/ledger/collector/correction/origin_correction.go
  • openmeter/ledger/collector/correction/origin_positions.go
  • openmeter/ledger/collector/correction/origin_references.go
  • openmeter/ledger/collector/correction/plan.go
  • openmeter/ledger/creditvoid/service.go
  • openmeter/ledger/errors.go
  • openmeter/ledger/fbo/consume.go
  • openmeter/ledger/recognizer/sources.go
  • openmeter/ledger/transactions/provenance.go
🚧 Files skipped from review as they are similar to previous changes: 1
  • openmeter/billing/README.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 4 remain after this review.

📝 Walkthrough

The pull request adds shared structured errors and diagnostic extraction. Ledger failures now expose stable codes and reasons. FBO balance reads report negative sources through metrics and warning logs. Collector and test setups now pass OpenTelemetry meters.

Changes: Structured errors and ledger diagnostics

Layer / File(s) Summary
Structured error contract and validation handling
pkg/models/structured_error.go, pkg/models/validationissue.go, pkg/errorsx/*, openmeter/billing/validationissue.go, pkg/framework/commonhttp/errors_test.go
System errors and validation issues share implementation but remain distinct. Billing conversion requires explicit intent. Error handlers extract codes and reasons from error chains.
Structured reasons for ledger failures
openmeter/ledger/advance/*, openmeter/ledger/breakage/*, openmeter/ledger/collector/correction/*, openmeter/ledger/creditvoid/*, openmeter/ledger/fbo/consume.go, openmeter/ledger/recognizer/*, openmeter/ledger/transactions/*
Ledger failure paths now return structured errors with stable reason attributes. Tests inspect selected reasons and failed transaction state.
Negative FBO balance reporting and meter wiring
openmeter/ledger/fbo/*, openmeter/ledger/collector/service.go, app/common/*, **/*_test.go
FBO and collector configurations require meters. Negative source balances increment an observation counter and produce warning logs while remaining excluded from spendable balances. Test setups provide no-op meters.

Priority: ➖ Normal

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

Change: Feature

Suggested reviewers: turip

Merge Risk: ⚪ Minimal · up to 299ba

The reviewed changes are mergeable after normal checks; no actionable failure was identified in error handling, diagnostics, or meter wiring.

Pre-merge checks: Passed 4
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main changes: ledger accounting diagnostics and balance telemetry.
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.
✨ Finishing Touches: 💡 1
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
🛠️ Fix failing CI checks: 💡
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Comment @coderabbitai help to get the list of available commands.

@GAlexIHU
GAlexIHU force-pushed the codex/ledger-error-telemetry branch from 3f553b1 to dcbd79d Compare October 19, 2026 13:17
Comment thread openmeter/ledger/collector/service.go
Comment thread openmeter/ledger/recognizer/sources.go Outdated
func (s *service) recognitionGroup(ctx context.Context, namespace, id string, groups map[string]ledger.TransactionGroup) (ledger.TransactionGroup, error) {
if id == "" {
return nil, fmt.Errorf("recognition lineage is missing its allocation or backing transaction group")
return nil, models.NewError("ledger_recognition_failed", "recognition lineage is missing its allocation or backing transaction group", models.WithAttribute("reason", "ledger_recognition_lineage_reference_missing"))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use a constant for the error codes.

},
}, nil
case models.Error:
if ordinaryErrorSeverity == "" {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a comment here, that any generic error not wrapped using WrapAsValidationIssue is considered a system error.

@GAlexIHU
GAlexIHU force-pushed the codex/ledger-error-telemetry branch from bea52da to 299ba20 Compare October 21, 2026 13:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release-note/misc Miscellaneous changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants