Fix/sentry cleanup again

[sleidig]

Summary by CodeRabbit

• New Features

  • Added configurable Sentry transaction tracing with sampling rate control to manage monitoring costs.

• Improvements

  • Enhanced error detection and logging for better diagnostics of authentication and transient failures.

• Documentation

  • Updated configuration templates and README with Sentry tracing setup instructions.

• Tests

  • Added comprehensive error classification and error handling test coverage.

[coderabbitai]

Warning

Rate limit exceeded

@sleidig has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 15 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 38ed342e-b4b7-402a-80b1-0be29225445e

📥 Commits

Reviewing files that changed from the base of the PR and between b13689d and 0c6e6f7.

📒 Files selected for processing (6)

• src/common/http-error-classification.spec.ts
• src/common/http-error-classification.ts
• src/couchdb/document-changes.service.spec.ts
• src/couchdb/document-changes.service.ts
• src/permissions/rules/rules.service.spec.ts
• src/permissions/rules/rules.service.ts

📝 Walkthrough

Walkthrough

This PR introduces HTTP error classification helpers to distinguish authentication and transient errors across services, applies them in CouchDB and permissions services with structured retry logging and differentiated log levels, and adds configurable Sentry transaction tracing via environment variable with validation.

Changes

HTTP error classification and service retry handling

Layer / File(s)	Summary
HTTP error classification helpers src/common/http-error-classification.ts, src/common/http-error-classification.spec.ts	Exports isAuthHttpError and isLikelyTransientError functions that classify errors by HTTP status code (401/403 for auth, 408/425/429/5xx for transient) or error message markers (connection errors, timeouts, gateway errors). Internal normalizeErrorText converts exception responses and error stacks into lowercase text for substring matching. Tests verify classification across authenticated/unauthenticated cases and transient/non-transient error messages.
DocumentChangesService error classification and logging src/couchdb/document-changes.service.ts, src/couchdb/document-changes.service.spec.ts	Replaces private isAuthError with imported classification helpers. Refactors logFeedError to build structured log context (failureCount, auth/transient flags, error text) and use logger.log for transient non-auth failures, logger.warn for others during backoff, and logger.error for sustained outages. Tests cover non-transient and transient feed error scenarios with expected log levels and context.
RulesService initial permission load retry logging src/permissions/rules/rules.service.ts, src/permissions/rules/rules.service.spec.ts	Updates loadInitialPermissions retry loop to classify errors and build structured context (DB, retry delay, transient flag, error message). Chooses logger.log for transient non-auth and logger.warn for non-transient. Tests verify log level selection and critical error message on startup abort after retry budget exhaustion.

Sentry transaction traces sample rate configuration

Layer / File(s)	Summary
Sentry configuration with traces sample rate src/sentry.configuration.ts	Updates SentryConfiguration interface to include TRACES_SAMPLE_RATE: number. Adds parseSampleRate() validator (must be finite and 0.0–1.0, warns on invalid, falls back to 0.02). Updates loadSentryConfiguration() to read SENTRY_TRACES_SAMPLE_RATE environment variable and SDK initialization to use configured rate instead of hardcoded 1.0. Success log includes configured sample rate.
Environment variable documentation .env.template, README.md, src/config/app.yaml	Documents SENTRY_TRACES_SAMPLE_RATE across environment template, YAML config, and README, specifying valid range 0.0–1.0 and default 0.02 to control transaction ingestion volume and cost.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Aam-Digital/replication-backend#240: Also modifies RulesService.loadInitialPermissions in src/permissions/rules/rules.service.ts to change error classification and retry handling logic for transient errors.

Poem

🐰 Errors now speak clearly—auth or transient woes,
Logs flow with context through the retry ballet,
Sentry traces sampled at a measured pace,
Services recover gracefully, with structured grace,
The warren's observability grows ever bright! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% 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 is vague and generic, using 'cleanup' without clearly conveying the main technical changes to Sentry error classification and transaction tracing.	Consider a more descriptive title such as 'Add Sentry error classification helpers and configurable transaction tracing' to better reflect the primary changes.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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 fix/sentry-cleanup-again

---

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: 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 `@src/common/http-error-classification.ts`:
- Around line 42-44: The code builds a detail string using
JSON.stringify(response) which can throw on non-serializable payloads; wrap the
serialization in a try/catch inside the function that computes detail (the code
around response and err.getStatus(), used by isLikelyTransientError()), and on
failure fall back to a safe representation (e.g., use util.inspect(response,
{depth: null}) or response?.toString() or a literal like '[unserializable
response]'); ensure the catch does not rethrow and the final returned string
uses that fallback detail and still calls err.getStatus().

🪄 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: 5ffee215-a46d-4d61-9546-3d3673ac4de8

📥 Commits

Reviewing files that changed from the base of the PR and between 196b0ae and b13689d.

📒 Files selected for processing (10)

• .env.template
• README.md
• src/common/http-error-classification.spec.ts
• src/common/http-error-classification.ts
• src/config/app.yaml
• src/couchdb/document-changes.service.spec.ts
• src/couchdb/document-changes.service.ts
• src/permissions/rules/rules.service.spec.ts
• src/permissions/rules/rules.service.ts
• src/sentry.configuration.ts