Skip to content

telemetry header handler - #129

Merged
cb-alish merged 12 commits into
masterfrom
feat/chargebee-telemetry
Nov 16, 2026
Merged

cb-alish merged 12 commits into
masterfrom
feat/chargebee-telemetry

Conversation

@cb-karthikp

@cb-karthikp cb-karthikp commented Aug 7, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Adds opt-in support for Chargebee response telemetry.

When enabled, the SDK asks Chargebee to include an X-Chargebee-Telemetry response header. The header carries server-side timing, third-party gateway timing, and the features used to serve the request. The SDK parses it and passes the values to your telemetryAdapter as span attributes, for both successful and failed requests.

const chargebee = new Chargebee({
  site: 'your-site',
  apiKey: 'your-api-key',
  telemetryAdapter: myAdapter,      // required
  preferChargebeeTelemetry: true,   // default: false
});

Example header:

cb;start_time=@1781280400;res_wait_time_ms=90;tp_time_ms=1350;time_ms=3800, tp-avalara;time_ms=730, tp-stripe;pm=card;time_ms=620, ft-consolidated_invoicing, ft-account_hierarchy

Attributes added to result.endAttributes:

Header part Span attribute
Raw value http.response.header.x-chargebee-telemetry
cb;time_ms=3800 chargebee.telemetry.cb.time_ms = 3800
tp-stripe;pm=card chargebee.telemetry.tp.stripe.pm = "card"
ft-* items chargebee.telemetry.features = ["consolidated_invoicing", "account_hierarchy"]

Values keep their types: numbers, booleans, dates as epoch seconds, and strings. A malformed header never fails the request; only the raw value is recorded.

Changes

  • New preferChargebeeTelemetry config option. When set along with a telemetryAdapter, requests include Prefer: chargebee-telemetry=include. A Prefer header you set yourself is left untouched.
  • RequestTelemetryResult now includes responseHeaders, and endAttributes values can be string | number | boolean | string[].
  • New exports: CHARGEBEE_TELEMETRY_PREFER_HEADER, CHARGEBEE_TELEMETRY_PREFER_VALUE.
  • The built-in OpenTelemetry adapter now picks up a tracer provider registered after the SDK is imported.
  • README: new response telemetry section.

This is independent of the anonymous SDK telemetry header (sdkTelemetryEnabled).

Adds opt-in Chargebee telemetry header support. The adapter adds Prefer: chargebee-telemetry=include, parses X-Chargebee-Telemetry from successful and failed responses, and records typed request-end attributes. Adds configuration, types, exports, documentation, and tests.

@snyk-io

snyk-io Bot commented Aug 7, 2026 •

Copy link
Copy Markdown

✅ Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
✅ Open Source Security 0 0 0 0 0 issues
✅ Licenses 0 0 0 0 0 issues
✅ Code Security 0 0 0 0 0 issues
✅ Secrets 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@coderabbitai

coderabbitai Bot commented Aug 7, 2026 •

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

The PR adds opt-in response-header telemetry. It requests X-Chargebee-Telemetry, parses its values, merges them into request-end telemetry, and preserves response headers for successful and failed requests.

Changes

Response Header Telemetry

Layer / File(s) Summary
Telemetry contract and header parser
src/telemetry/types.ts, src/telemetry/chargebeeTelemetryHeaderParser.ts, test/chargebeeTelemetryHeaderParser.test.ts
Telemetry types support response headers and boolean or string-array attributes. The parser handles typed values, quoted strings, delimiters, and malformed input.
Response-header adapter integration
src/telemetry/TelemetryAdapter.ts, test/telemetryAdapter.test.ts
TelemetryAdapter applies the opt-in header, performs case-insensitive lookup, extracts error headers, parses X-Chargebee-Telemetry, and merges response attributes into request-end attributes.
Request preference and result propagation
src/RequestWrapper.ts, test/requestWrapper.test.ts
RequestWrapper applies the preference when enabled with telemetry and includes response headers in successful and failed telemetry results.
Configuration, exports, and documentation
src/types.d.ts, types/index.d.ts, src/telemetry/index.ts, src/chargebee.cjs.ts, src/chargebee.esm.ts, README.md, test/publicTypes.test.ts
Configuration types, package exports, telemetry exports, public declarations, tests, and README instructions describe the response telemetry option and constants.
Dynamic tracer access
src/telemetry/otel.ts
Request-start span creation now retrieves the Chargebee tracer through getTracer().

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RequestWrapper
  participant ChargebeeAPI
  participant TelemetryAdapter
  participant RequestEndSpan
  RequestWrapper->>ChargebeeAPI: send Prefer: chargebee-telemetry=include
  ChargebeeAPI-->>RequestWrapper: return X-Chargebee-Telemetry
  RequestWrapper->>TelemetryAdapter: pass response headers
  TelemetryAdapter->>TelemetryAdapter: parse response telemetry
  TelemetryAdapter->>RequestEndSpan: merge response attributes
Loading
🚥 Pre-merge checks | ✅ 1

✅ Passed checks (1 passed)

Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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/telemetry/chargebeeTelemetryHeaderParser.ts`:
- Around line 188-234: Update splitOnDelimiter, indexOfParameterSeparator, and
indexOfEquals to recognize backslash-escaped quotes while scanning quoted
values, so escaped quotes do not change inQuotes state and subsequent delimiters
are detected correctly. Add an end-to-end parser test covering an escaped quote
followed by another list item.
🪄 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: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: cdcc1b43-61e8-4d18-a788-4bf6d00f934d

📥 Commits

Reviewing files that changed from the base of the PR and between 29fb518 and e2221ed.

📒 Files selected for processing (7)
  • src/RequestWrapper.ts
  • src/telemetry/TelemetryAdapter.ts
  • src/telemetry/chargebeeTelemetryHeaderParser.ts
  • src/telemetry/index.ts
  • src/telemetry/types.ts
  • test/chargebeeTelemetryHeaderParser.test.ts
  • test/telemetryAdapter.test.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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 `@types/index.d.ts`:
- Around line 188-193: Declare the public constants
CHARGEBEE_TELEMETRY_PREFER_HEADER and CHARGEBEE_TELEMETRY_PREFER_VALUE in
types/index.d.ts with their matching literal string types, and add a type-level
import test confirming both are publicly importable from the package entry
point.
🪄 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: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: a5d8b3e0-246f-4a30-84ea-e29f000e43db

📥 Commits

Reviewing files that changed from the base of the PR and between e0d8411 and de9f197.

📒 Files selected for processing (13)
  • README.md
  • src/RequestWrapper.ts
  • src/chargebee.cjs.ts
  • src/chargebee.esm.ts
  • src/telemetry/TelemetryAdapter.ts
  • src/telemetry/chargebeeTelemetryHeaderParser.ts
  • src/telemetry/index.ts
  • src/telemetry/types.ts
  • src/types.d.ts
  • test/chargebeeTelemetryHeaderParser.test.ts
  • test/requestWrapper.test.ts
  • test/telemetryAdapter.test.ts
  • types/index.d.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • src/RequestWrapper.ts
  • src/telemetry/index.ts
  • src/telemetry/chargebeeTelemetryHeaderParser.ts
  • test/chargebeeTelemetryHeaderParser.test.ts
  • src/telemetry/types.ts

Comment thread types/index.d.ts Resolved
@coderabbitai coderabbitai Bot mentioned this pull request Aug 10, 2026
Co-authored-by: Cursor <cursoragent@cursor.com>
Bump version to 3.37.0 and add changelog and README links to the
response telemetry docs.
Validate integers and dates against the RFC 9651 grammar (max 15
digits). A malformed value now skips only that parameter in both SDKs,
instead of Java dropping the whole header and Node emitting NaN or a
truncated/imprecise number.
RFC 9651 treats a parameter without a value (e.g. cb;cached) as boolean
true. Previously it aborted parsing and dropped all telemetry attributes.
Malformed parameters (empty key, bad value) and members with an empty
token are now skipped individually so the rest of the header is kept,
matching the spec's forward-compatibility guidance.
Existing adapters must not be affected by response telemetry. Parsed
X-Chargebee-Telemetry values (and the raw header) now go in a separate
responseTelemetryAttributes field (Java: getResponseTelemetryAttributes())
instead of being merged into endAttributes.

- Node: endAttributes keeps its Record<string, string | number> type, so
  custom TypeScript adapters that narrow values still compile. The
  built-in OTel adapter forwards both maps.
- Java: getEndAttributes() is unchanged; existing constructors are kept.
- endAttributes is identical to the previous release in all scenarios.
extractResponseHeaders returned a native Headers instance as-is when a
custom HTTP client threw an error carrying one (err.response.headers or
err.headers). Its entries are not own properties, so the
X-Chargebee-Telemetry lookup found nothing and telemetry was silently
dropped on that error. Convert Headers to a plain record; plain header
objects are returned unchanged.
@cb-alish
cb-alish marked this pull request as ready for review November 16, 2026 10:21
@cb-alish
cb-alish merged commit 356a2e3 into master Nov 16, 2026
7 checks passed
@cb-alish
cb-alish deleted the feat/chargebee-telemetry branch November 16, 2026 10:22
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.

2 participants