diff --git a/CHANGELOG.md b/CHANGELOG.md index e1d0ebc1..8d4bd2a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +### v4.21.0 (2026-11-13) +* * * +### New Features +* Added [response telemetry](https://apidocs.chargebee.com/docs/api/response-telemetry) support (Beta). Call `ChargebeeClient.Builder#preferChargebeeTelemetry(true)` alongside a `telemetryAdapter` to have the SDK send `Prefer: chargebee-telemetry=include` on each request. The SDK parses the `X-Chargebee-Telemetry` response header on both successful and failed responses and passes it to your adapter in the new `RequestTelemetryResult#getResponseTelemetryAttributes()`: the raw value under `http.response.header.x-chargebee-telemetry` and typed parsed values under `chargebee.telemetry.*`. A malformed header never fails the API call. Setting `preferChargebeeTelemetry` without a `telemetryAdapter` has no effect, and a `Prefer` header you set on the request yourself is left unchanged. +* No change for existing integrations: `getEndAttributes()` returns the same keys and value types as before, and existing `RequestTelemetryResult` constructors are kept. Response telemetry values (`String`, `Long`, `Double`, `Boolean`, `List`) appear only in `getResponseTelemetryAttributes()`; see the updated `OtelTelemetryAdapter` example in the README to forward them. + + ### v4.20.0 (2026-11-13) ### New Resources: diff --git a/README.md b/README.md index ca4485e7..0bb98e82 100644 --- a/README.md +++ b/README.md @@ -711,6 +711,65 @@ The SDK builds standardized span attributes (`ctx.getStartAttributes()`, `result Spans are named `chargebee.{resource}.{operation}` (e.g. `chargebee.subscription.create`). +#### Server-side timing telemetry (Beta) + +> **Beta.** `X-Chargebee-Telemetry` response parsing and `preferChargebeeTelemetry` are in beta. Header availability, wire format, and SDK behavior may change. + +Chargebee returns `X-Chargebee-Telemetry` only when the client opts in with `Prefer: chargebee-telemetry=include`. Call `.preferChargebeeTelemetry(true)` on the client builder to have the SDK add that header on each request when a `telemetryAdapter` is configured (parsed into `chargebee.telemetry.*` span attributes). You can also set the `Prefer` header yourself on individual requests. + +For the header format and the meaning of each field, see [Response telemetry](https://apidocs.chargebee.com/docs/api/response-telemetry) in the API docs. + +On select APIs, Chargebee may include an `X-Chargebee-Telemetry` response header with a server-side timing breakdown — treat it as optional enrichment, not a required contract. + +When the header is present and a `telemetryAdapter` is configured, the SDK passes these attributes to your adapter in `result.getResponseTelemetryAttributes()`, in two layers. They're kept separate from `result.getEndAttributes()`, so existing adapters see no change; forward both maps to your span to record them. + +1. **Raw** — the full header string under `http.response.header.x-chargebee-telemetry` (audit, debug, or custom parsing) +2. **Parsed** — typed flat attributes under `chargebee.telemetry.*` (ready for APM dashboards without writing a parser) + +The header value is an [RFC 9651](https://www.rfc-editor.org/rfc/rfc9651) `sf-list`: comma-separated segments, each optionally followed by semicolon-separated `key=value` parameters. + +``` +X-Chargebee-Telemetry: cb;start_time_epoch=1781280400;time_ms=3800, tp-stripe;pm=card;time_ms=620, ft-account_hierarchy +``` + +| Segment | Meaning | Parsed span attributes | +|---|---|---| +| `cb;…` | Chargebee processing time | `chargebee.telemetry.cb.{param}` — e.g. `time_ms`, `start_time_epoch`, `res_wait_time_ms`, `tp_time_ms` | +| `tp-{provider};…` | Third-party call time (Stripe, Avalara, …) | `chargebee.telemetry.tp.{provider}.{param}` — e.g. `chargebee.telemetry.tp.stripe.time_ms` | +| `ft-{feature}` | Feature flag active on this request (bare token, no params) | Collected into `chargebee.telemetry.features` (`string[]`) | + +Parameter values are typed by RFC 9651 wire format and mapped to OTel-friendly types: + +| Wire format | Example | OTel type | +|---|---|---| +| sf-date (`@epoch`) | `start_time=@1781280400` | `long` (Unix seconds) | +| sf-integer | `time_ms=3800` | `long` | +| sf-decimal | `ratio=99.9` | `double` | +| sf-token (bare word) | `pm=card` | `string` | +| sf-string (quoted) | `desc="hello world"` | `string` | +| sf-boolean | `enabled=?1` / `?0` | `boolean` | +| sf-binary | `payload=:aGVsbG8=:` | `string` (base64 payload) | + +For the example header above, `result.getResponseTelemetryAttributes()` at span end contains: + +``` +http.response.header.x-chargebee-telemetry → "cb;start_time_epoch=1781280400;time_ms=3800, tp-stripe;pm=card;time_ms=620, ft-account_hierarchy" +chargebee.telemetry.cb.start_time_epoch → 1781280400 +chargebee.telemetry.cb.time_ms → 3800 +chargebee.telemetry.tp.stripe.time_ms → 620 +chargebee.telemetry.tp.stripe.pm → "card" +chargebee.telemetry.features → ["account_hierarchy"] +``` + +**Behavior:** + +- Header **absent** → no telemetry header attributes are added; the span is unaffected. +- Header **partly malformed** → malformed parameters or members are skipped and the rest are still parsed. A parameter without a value (e.g. `cb;cached`) is parsed as `true`, per RFC 9651. +- Header **present but unparseable** → only the raw `http.response.header.x-chargebee-telemetry` attribute is emitted; the API call is never failed or delayed by parsing. +- Parsed timing fields such as `chargebee.telemetry.cb.time_ms` are numeric (`long`) so backends like Datadog, New Relic, and Honeycomb can filter, average, and chart percentiles out of the box. + +Use the included `OtelTelemetryAdapter` example below as-is to forward both raw and parsed attributes to your exporter. + #### OpenTelemetry example ```kotlin @@ -767,6 +826,7 @@ import io.opentelemetry.api.trace.SpanKind; import io.opentelemetry.api.trace.StatusCode; import io.opentelemetry.api.trace.Tracer; import io.opentelemetry.context.Context; +import java.util.List; import java.util.Map; class OtelTelemetryAdapter implements TelemetryAdapter { @@ -805,18 +865,8 @@ class OtelTelemetryAdapter implements TelemetryAdapter { return; } Span span = (Span) handle; - result - .getEndAttributes() - .forEach( - (k, v) -> { - if (v instanceof String) { - span.setAttribute(k, (String) v); - } else if (v instanceof Long) { - span.setAttribute(k, (Long) v); - } else if (v instanceof Integer) { - span.setAttribute(k, ((Integer) v).longValue()); - } - }); + setAttributes(span, result.getEndAttributes()); + setAttributes(span, result.getResponseTelemetryAttributes()); // X-Chargebee-Telemetry (Beta) if (result.getError() != null) { span.setStatus(StatusCode.ERROR, result.getError().getMessage()); } else { @@ -824,6 +874,27 @@ class OtelTelemetryAdapter implements TelemetryAdapter { } span.end(); } + + private static void setAttributes(Span span, Map attributes) { + attributes.forEach( + (k, v) -> { + if (v instanceof String) { + span.setAttribute(k, (String) v); + } else if (v instanceof Long) { + span.setAttribute(k, (Long) v); + } else if (v instanceof Integer) { + span.setAttribute(k, ((Integer) v).longValue()); + } else if (v instanceof Double) { + span.setAttribute(k, (Double) v); + } else if (v instanceof Boolean) { + span.setAttribute(k, (Boolean) v); + } else if (v instanceof List) { + @SuppressWarnings("unchecked") + List values = (List) v; + span.setAttribute(AttributeKey.stringArrayKey(k), values); + } + }); + } } ChargebeeClient client = diff --git a/VERSION b/VERSION index bafdf705..7c6be317 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.20.0 +4.21.0 diff --git a/build.gradle.kts b/build.gradle.kts index 6b4790d8..30469144 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -7,7 +7,7 @@ plugins { } group = "com.chargebee" -version = "4.20.0" +version = "4.21.0" description = "Java client library for ChargeBee" // Project metadata diff --git a/src/main/java/com/chargebee/v4/client/ChargebeeClient.java b/src/main/java/com/chargebee/v4/client/ChargebeeClient.java index ee34e676..b75d9b1c 100644 --- a/src/main/java/com/chargebee/v4/client/ChargebeeClient.java +++ b/src/main/java/com/chargebee/v4/client/ChargebeeClient.java @@ -46,6 +46,7 @@ public final class ChargebeeClient extends ClientMethodsImpl implements AutoClos private final TelemetryAdapter telemetryAdapter; private final boolean sdkTelemetryEnabled; private final SdkTelemetryState sdkTelemetryState = new SdkTelemetryState(); + private final boolean preferChargebeeTelemetry; private final ScheduledExecutorService retryScheduler; // Auto-generated service registry for lazy loading @@ -65,6 +66,7 @@ private ChargebeeClient(Builder builder) { this.clientHeaders = new RequestContext(builder.clientHeaders.getHeaders()); this.telemetryAdapter = builder.telemetryAdapter; this.sdkTelemetryEnabled = builder.sdkTelemetryEnabled; + this.preferChargebeeTelemetry = builder.preferChargebeeTelemetry; this.retryScheduler = Executors.newSingleThreadScheduledExecutor(r -> { Thread t = new Thread(r, "chargebee-retry-scheduler"); t.setDaemon(true); @@ -105,6 +107,7 @@ public static Builder builder(String apiKey, String siteName) { /** Internal SDK telemetry state; not part of the supported public API. */ public SdkTelemetryState getSdkTelemetryState() { return sdkTelemetryState; } + public boolean isPreferChargebeeTelemetry() { return preferChargebeeTelemetry; } public String getSdkVersion() { return getVersion(); @@ -586,6 +589,7 @@ public static final class Builder { private RequestInterceptor requestInterceptor; private TelemetryAdapter telemetryAdapter; private boolean sdkTelemetryEnabled = true; + private boolean preferChargebeeTelemetry = false; private final RequestContext clientHeaders = new RequestContext(); private Builder() {} @@ -618,6 +622,7 @@ public Builder timeout(int connectTimeoutMs, int readTimeoutMs) { * independent of {@link #telemetryAdapter(TelemetryAdapter)}. */ public Builder sdkTelemetryEnabled(boolean sdkTelemetryEnabled) { this.sdkTelemetryEnabled = sdkTelemetryEnabled; return this; } + public Builder preferChargebeeTelemetry(boolean preferChargebeeTelemetry) { this.preferChargebeeTelemetry = preferChargebeeTelemetry; return this; } // Header helpers public Builder header(String name, String value) { diff --git a/src/main/java/com/chargebee/v4/telemetry/ChargebeeTelemetryHeaderParser.java b/src/main/java/com/chargebee/v4/telemetry/ChargebeeTelemetryHeaderParser.java new file mode 100644 index 00000000..26693d18 --- /dev/null +++ b/src/main/java/com/chargebee/v4/telemetry/ChargebeeTelemetryHeaderParser.java @@ -0,0 +1,273 @@ +/* + * Copyright 2026 Chargebee Inc. + */ + +package com.chargebee.v4.telemetry; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.regex.Pattern; + +/** Parses the {@code X-Chargebee-Telemetry} response header into OpenTelemetry span attributes. */ +public final class ChargebeeTelemetryHeaderParser { + + static final String SF_DATE_PREFIX = "@"; + static final String SF_BOOLEAN_TRUE = "?1"; + static final String SF_BOOLEAN_FALSE = "?0"; + + // RFC 9651 sf-integer: at most 15 digits, so values always fit a long (and a JS number). + private static final Pattern INTEGER_PATTERN = Pattern.compile("-?\\d+"); + private static final Pattern SF_INTEGER_PATTERN = Pattern.compile("-?\\d{1,15}"); + private static final Pattern DECIMAL_PATTERN = Pattern.compile("-?\\d+\\.\\d+"); + + private ChargebeeTelemetryHeaderParser() { + // utility class + } + + /** + * Parses a raw {@code X-Chargebee-Telemetry} header value into typed span attributes. + * + * @param headerValue raw header string + * @return parsed attributes, or empty map when input is null/blank or structurally invalid + */ + public static Map parseToSpanAttributes(String headerValue) { + if (headerValue == null || headerValue.trim().isEmpty()) { + return Collections.emptyMap(); + } + + try { + Map attributes = new HashMap<>(); + List features = new ArrayList<>(); + + for (String item : splitListItems(headerValue)) { + parseListItem(item, attributes, features); + } + + if (!features.isEmpty()) { + attributes.put(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_FEATURES, features); + } + + return attributes.isEmpty() ? Collections.emptyMap() : attributes; + } catch (RuntimeException ex) { + return Collections.emptyMap(); + } + } + + private static void parseListItem( + String item, Map attributes, List features) { + String trimmed = item.trim(); + if (trimmed.isEmpty()) { + return; + } + + int separator = indexOfParameterSeparator(trimmed); + String token = separator < 0 ? trimmed : trimmed.substring(0, separator).trim(); + if (token.isEmpty()) { + return; // skip only this member + } + + if (token.startsWith(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_FT_PREFIX)) { + features.add(token.substring(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_FT_PREFIX.length())); + return; + } + + String attributePrefix = segmentAttributePrefix(token); + if (separator >= 0) { + parseParameters(trimmed.substring(separator + 1), attributePrefix, attributes); + } + } + + private static String segmentAttributePrefix(String token) { + if (TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_CB_SEGMENT.equals(token)) { + return TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_CB_PREFIX; + } + if (token.startsWith(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_TP_PREFIX)) { + return TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_TP_ATTRIBUTE_PREFIX + + token.substring(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_TP_PREFIX.length()) + + "."; + } + return TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFIX + token + "."; + } + + private static void parseParameters( + String parametersSection, String attributePrefix, Map attributes) { + for (String parameter : splitParameters(parametersSection)) { + parseParameter(parameter, attributePrefix, attributes); + } + } + + private static void parseParameter( + String parameter, String attributePrefix, Map attributes) { + String trimmed = parameter.trim(); + if (trimmed.isEmpty()) { + return; + } + + // Malformed parameters are skipped individually so the rest of the header is kept. + int equalsIndex = indexOfEquals(trimmed); + if (equalsIndex < 0) { + // RFC 9651: a parameter without a value is boolean true (e.g. "cb;cached"). + attributes.put(attributePrefix + trimmed, Boolean.TRUE); + return; + } + + String key = trimmed.substring(0, equalsIndex).trim(); + String rawValue = trimmed.substring(equalsIndex + 1).trim(); + if (key.isEmpty()) { + return; + } + + Object value; + try { + value = parseScalarValue(rawValue); + } catch (IllegalArgumentException ex) { + return; + } + if (value != null) { + attributes.put(attributePrefix + key, value); + } + } + + /** + * Parses one RFC 9651 bare item. + * + * @return the typed value, or {@code null} when the value is a malformed sf-integer or sf-date + * (the caller skips only that parameter and keeps the rest of the header) + */ + static Object parseScalarValue(String rawValue) { + if (rawValue == null || rawValue.isEmpty()) { + throw new IllegalArgumentException("missing scalar value"); + } + + if (rawValue.startsWith(SF_DATE_PREFIX)) { + return parseSfInteger(rawValue.substring(SF_DATE_PREFIX.length())); + } + if (SF_BOOLEAN_TRUE.equals(rawValue)) { + return Boolean.TRUE; + } + if (SF_BOOLEAN_FALSE.equals(rawValue)) { + return Boolean.FALSE; + } + if (rawValue.startsWith(":") && rawValue.endsWith(":") && rawValue.length() >= 2) { + return rawValue.substring(1, rawValue.length() - 1); + } + if (rawValue.startsWith("\"")) { + return parseStringValue(rawValue); + } + if (INTEGER_PATTERN.matcher(rawValue).matches()) { + return parseSfInteger(rawValue); + } + if (DECIMAL_PATTERN.matcher(rawValue).matches()) { + return Double.parseDouble(rawValue); + } + return rawValue; + } + + private static Long parseSfInteger(String value) { + return SF_INTEGER_PATTERN.matcher(value).matches() ? Long.valueOf(value) : null; + } + + private static String parseStringValue(String rawValue) { + if (rawValue.length() < 2 || rawValue.charAt(rawValue.length() - 1) != '"') { + throw new IllegalArgumentException("invalid sf-string value"); + } + + StringBuilder decoded = new StringBuilder(); + for (int i = 1; i < rawValue.length() - 1; i++) { + char current = rawValue.charAt(i); + if (current == '\\') { + if (i + 1 >= rawValue.length() - 1) { + throw new IllegalArgumentException("invalid sf-string escape"); + } + decoded.append(rawValue.charAt(++i)); + } else { + decoded.append(current); + } + } + return decoded.toString(); + } + + private static List splitListItems(String input) { + return splitOnDelimiter(input, ','); + } + + private static List splitParameters(String input) { + return splitOnDelimiter(input, ';'); + } + + private static List splitOnDelimiter(String input, char delimiter) { + List parts = new ArrayList<>(); + StringBuilder current = new StringBuilder(); + boolean inQuotes = false; + + for (int i = 0; i < input.length(); i++) { + char currentChar = input.charAt(i); + if (currentChar == '"') { + if (!isEscapedQuote(input, i)) { + inQuotes = !inQuotes; + } + current.append(currentChar); + } else if (currentChar == delimiter && !inQuotes) { + addIfNotBlank(parts, current); + current = new StringBuilder(); + } else { + current.append(currentChar); + } + } + + addIfNotBlank(parts, current); + return parts; + } + + private static int indexOfParameterSeparator(String item) { + boolean inQuotes = false; + for (int i = 0; i < item.length(); i++) { + char current = item.charAt(i); + if (current == '"') { + if (!isEscapedQuote(item, i)) { + inQuotes = !inQuotes; + } + } else if (current == ';' && !inQuotes) { + return i; + } + } + return -1; + } + + private static int indexOfEquals(String parameter) { + boolean inQuotes = false; + for (int i = 0; i < parameter.length(); i++) { + char current = parameter.charAt(i); + if (current == '"') { + if (!isEscapedQuote(parameter, i)) { + inQuotes = !inQuotes; + } + } else if (current == '=' && !inQuotes) { + return i; + } + } + return -1; + } + + /** Returns true when {@code input[index]} is a quote escaped by a preceding backslash. */ + private static boolean isEscapedQuote(String input, int index) { + int backslashes = 0; + for (int i = index - 1; i >= 0 && input.charAt(i) == '\\'; i--) { + backslashes++; + } + return backslashes % 2 == 1; + } + + private static void addIfNotBlank(List parts, StringBuilder current) { + if (current.length() == 0) { + return; + } + String value = current.toString().trim(); + if (!value.isEmpty()) { + parts.add(value); + } + } +} diff --git a/src/main/java/com/chargebee/v4/telemetry/RequestTelemetryResult.java b/src/main/java/com/chargebee/v4/telemetry/RequestTelemetryResult.java index e949d922..76426806 100644 --- a/src/main/java/com/chargebee/v4/telemetry/RequestTelemetryResult.java +++ b/src/main/java/com/chargebee/v4/telemetry/RequestTelemetryResult.java @@ -17,17 +17,31 @@ public final class RequestTelemetryResult { private final long durationMs; private final RequestTelemetryError error; private final Map endAttributes; + private final Map responseTelemetryAttributes; public RequestTelemetryResult( int httpStatusCode, long durationMs, RequestTelemetryError error, Map endAttributes) { + this(httpStatusCode, durationMs, error, endAttributes, null); + } + + public RequestTelemetryResult( + int httpStatusCode, + long durationMs, + RequestTelemetryError error, + Map endAttributes, + Map responseTelemetryAttributes) { this.httpStatusCode = httpStatusCode; this.durationMs = durationMs; this.error = error; this.endAttributes = endAttributes == null ? Collections.emptyMap() : Collections.unmodifiableMap(endAttributes); + this.responseTelemetryAttributes = + responseTelemetryAttributes == null + ? Collections.emptyMap() + : Collections.unmodifiableMap(responseTelemetryAttributes); } public int getHttpStatusCode() { @@ -46,4 +60,15 @@ public RequestTelemetryError getError() { public Map getEndAttributes() { return endAttributes; } + + /** + * Span attributes from the {@code X-Chargebee-Telemetry} response header (Beta): the raw value + * under {@code http.response.header.x-chargebee-telemetry} and parsed values under {@code + * chargebee.telemetry.*}. Values may be {@code String}, {@code Long}, {@code Double}, {@code + * Boolean} or {@code List}. Empty when the header is absent. Kept separate from {@link + * #getEndAttributes()} so existing adapters are unaffected. + */ + public Map getResponseTelemetryAttributes() { + return responseTelemetryAttributes; + } } diff --git a/src/main/java/com/chargebee/v4/telemetry/TelemetryAdapterExecutor.java b/src/main/java/com/chargebee/v4/telemetry/TelemetryAdapterExecutor.java index bd7e8a1a..b0ce3c09 100644 --- a/src/main/java/com/chargebee/v4/telemetry/TelemetryAdapterExecutor.java +++ b/src/main/java/com/chargebee/v4/telemetry/TelemetryAdapterExecutor.java @@ -39,13 +39,14 @@ static Response around( return next.apply(request); } + Request telemetryRequest = maybeApplyResponseTelemetryPreferHeader(client, request); Map adapterHeaders = new HashMap<>(); - Object handle = startTelemetry(client, adapter, request, adapterHeaders); + Object handle = startTelemetry(client, adapter, telemetryRequest, adapterHeaders); long startTime = System.currentTimeMillis(); try { - Response response = next.apply(withHeaders(request, adapterHeaders)); - endTelemetrySuccess(adapter, handle, startTime, response.getStatusCode()); + Response response = next.apply(withHeaders(telemetryRequest, adapterHeaders)); + endTelemetrySuccess(adapter, handle, startTime, response); return response; } catch (RuntimeException err) { endTelemetryFailure(adapter, handle, startTime, err); @@ -63,18 +64,19 @@ static CompletableFuture aroundAsync( return next.apply(request); } + Request telemetryRequest = maybeApplyResponseTelemetryPreferHeader(client, request); Map adapterHeaders = new HashMap<>(); - Object handle = startTelemetry(client, adapter, request, adapterHeaders); + Object handle = startTelemetry(client, adapter, telemetryRequest, adapterHeaders); long startTime = System.currentTimeMillis(); - return next.apply(withHeaders(request, adapterHeaders)) + return next.apply(withHeaders(telemetryRequest, adapterHeaders)) .whenComplete( (response, throwable) -> { if (throwable != null) { Throwable cause = throwable.getCause() != null ? throwable.getCause() : throwable; endTelemetryFailure(adapter, handle, startTime, cause); } else { - endTelemetrySuccess(adapter, handle, startTime, response.getStatusCode()); + endTelemetrySuccess(adapter, handle, startTime, response); } }); } @@ -114,13 +116,16 @@ private static Object startTelemetry( /** Invokes {@link TelemetryAdapter#onRequestEnd} for a successful response. */ private static void endTelemetrySuccess( - TelemetryAdapter adapter, Object handle, long startTime, int httpStatusCode) { + TelemetryAdapter adapter, Object handle, long startTime, Response response) { try { adapter.onRequestEnd( handle, TelemetrySupport.buildRequestTelemetryResult( new TelemetrySupport.RequestTelemetryResultInput( - httpStatusCode, System.currentTimeMillis() - startTime, null))); + response.getStatusCode(), + System.currentTimeMillis() - startTime, + null, + response.getHeaders()))); } catch (Exception err) { LOGGER.log(Level.WARNING, "Telemetry adapter onRequestEnd failed: " + err.getMessage(), err); } @@ -138,7 +143,8 @@ private static void endTelemetryFailure( new TelemetrySupport.RequestTelemetryResultInput( httpStatusCode, System.currentTimeMillis() - startTime, - TelemetrySupport.extractRequestTelemetryError(err)))); + TelemetrySupport.extractRequestTelemetryError(err), + TelemetrySupport.extractResponseHeaders(err)))); } catch (Exception telemetryErr) { LOGGER.log( Level.WARNING, @@ -172,6 +178,18 @@ private static String extractApiPath(String baseUrl) { return path != null && !path.isEmpty() ? path : "/api/v2"; } + /** + * Adds {@code Prefer: chargebee-telemetry=include} when the client opted in via {@code + * ChargebeeClient.Builder#preferChargebeeTelemetry(boolean)}. + */ + private static Request maybeApplyResponseTelemetryPreferHeader( + ChargebeeClient client, Request request) { + if (!client.isPreferChargebeeTelemetry()) { + return request; + } + return TelemetrySupport.applyResponseTelemetryPreferHeader(request); + } + /** Returns a copy of {@code request} with {@code headers} applied. */ static Request withHeaders(Request request, Map headers) { Request updated = request; diff --git a/src/main/java/com/chargebee/v4/telemetry/TelemetryAttributeKeys.java b/src/main/java/com/chargebee/v4/telemetry/TelemetryAttributeKeys.java index 0421c9cd..cd44ca80 100644 --- a/src/main/java/com/chargebee/v4/telemetry/TelemetryAttributeKeys.java +++ b/src/main/java/com/chargebee/v4/telemetry/TelemetryAttributeKeys.java @@ -23,9 +23,23 @@ public final class TelemetryAttributeKeys { public static final String TELEMETRY_SPAN_NAME_PREFIX = "chargebee"; public static final String HTTP_REQUEST_HEADER_ATTRIBUTE_PREFIX = "http.request.header."; + public static final String HTTP_RESPONSE_HEADER_ATTRIBUTE_PREFIX = "http.response.header."; public static final String CHARGEBEE_TELEMETRY_HEADER_PREFIX = "chargebee-"; public static final String CHARGEBEE_TELEMETRY_HEADER_EXCLUDE_PREFIX = "chargebee-request-origin-"; + public static final String X_CHARGEBEE_TELEMETRY_HEADER = "x-chargebee-telemetry"; + public static final String CHARGEBEE_TELEMETRY_PREFER_HEADER = "Prefer"; + public static final String CHARGEBEE_TELEMETRY_PREFER_VALUE = "chargebee-telemetry=include"; + + public static final String CHARGEBEE_TELEMETRY_PREFIX = "chargebee.telemetry."; + + public static final String CHARGEBEE_TELEMETRY_CB_SEGMENT = "cb"; + public static final String CHARGEBEE_TELEMETRY_CB_PREFIX = CHARGEBEE_TELEMETRY_PREFIX + "cb."; + public static final String CHARGEBEE_TELEMETRY_TP_PREFIX = "tp-"; + public static final String CHARGEBEE_TELEMETRY_TP_ATTRIBUTE_PREFIX = + CHARGEBEE_TELEMETRY_PREFIX + "tp."; + public static final String CHARGEBEE_TELEMETRY_FT_PREFIX = "ft-"; + public static final String CHARGEBEE_TELEMETRY_FEATURES = CHARGEBEE_TELEMETRY_PREFIX + "features"; public static final String URL_FULL = "url.full"; public static final String HTTP_REQUEST_METHOD = "http.request.method"; diff --git a/src/main/java/com/chargebee/v4/telemetry/TelemetrySupport.java b/src/main/java/com/chargebee/v4/telemetry/TelemetrySupport.java index 3b6c2cb8..a00b214d 100644 --- a/src/main/java/com/chargebee/v4/telemetry/TelemetrySupport.java +++ b/src/main/java/com/chargebee/v4/telemetry/TelemetrySupport.java @@ -9,7 +9,10 @@ import com.chargebee.v4.exceptions.APIException; import com.chargebee.v4.exceptions.HttpException; +import com.chargebee.v4.transport.Request; +import com.chargebee.v4.transport.Response; import java.util.HashMap; +import java.util.List; import java.util.Locale; import java.util.Map; @@ -116,12 +119,22 @@ public static final class RequestTelemetryResultInput { private final int httpStatusCode; private final long durationMs; private final RequestTelemetryError error; + private final Map> responseHeaders; public RequestTelemetryResultInput( int httpStatusCode, long durationMs, RequestTelemetryError error) { + this(httpStatusCode, durationMs, error, null); + } + + public RequestTelemetryResultInput( + int httpStatusCode, + long durationMs, + RequestTelemetryError error, + Map> responseHeaders) { this.httpStatusCode = httpStatusCode; this.durationMs = durationMs; this.error = error; + this.responseHeaders = responseHeaders; } public int getHttpStatusCode() { @@ -135,6 +148,10 @@ public long getDurationMs() { public RequestTelemetryError getError() { return error; } + + public Map> getResponseHeaders() { + return responseHeaders; + } } /** Builds the span name {@code chargebee.{resource}.{operation}}. */ @@ -193,6 +210,30 @@ public static Map buildRequestHeaderSpanAttributes( return attributes; } + /** + * Captures the {@code X-Chargebee-Telemetry} response header as OpenTelemetry span attributes. + */ + public static Map buildResponseHeaderSpanAttributes( + Map> responseHeaders) { + Map attributes = new HashMap<>(); + if (responseHeaders == null) { + return attributes; + } + + String value = + getHeaderValueIgnoreCase( + responseHeaders, TelemetryAttributeKeys.X_CHARGEBEE_TELEMETRY_HEADER); + if (value != null) { + attributes.put( + TelemetryAttributeKeys.HTTP_RESPONSE_HEADER_ATTRIBUTE_PREFIX + + TelemetryAttributeKeys.X_CHARGEBEE_TELEMETRY_HEADER, + value); + attributes.putAll(ChargebeeTelemetryHeaderParser.parseToSpanAttributes(value)); + } + + return attributes; + } + /** Builds end-span attributes from the request result. */ public static Map buildRequestEndSpanAttributes( RequestTelemetryResultInput result) { @@ -243,7 +284,8 @@ public static RequestTelemetryResult buildRequestTelemetryResult( result.getHttpStatusCode(), result.getDurationMs(), result.getError(), - buildRequestEndSpanAttributes(result)); + buildRequestEndSpanAttributes(result), + buildResponseHeaderSpanAttributes(result.getResponseHeaders())); } /** Extracts Chargebee error details from {@code err}, if present. */ @@ -273,4 +315,72 @@ public static Integer extractHttpStatusCode(Throwable err) { } return null; } + + public static Map> extractResponseHeaders(Throwable err) { + if (err instanceof HttpException) { + Response response = ((HttpException) err).getResponse(); + if (response != null) { + return response.getHeaders(); + } + } + return null; + } + + /** + * Adds {@code Prefer: chargebee-telemetry=include} when not already set. + * + *

Chargebee returns {@code X-Chargebee-Telemetry} only when this header is present. + */ + public static void applyResponseTelemetryPreferHeader(Map requestHeaders) { + if (requestHeaders == null) { + return; + } + for (String name : requestHeaders.keySet()) { + if (name.equalsIgnoreCase(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)) { + return; + } + } + requestHeaders.put( + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER, + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_VALUE); + } + + /** + * Returns a copy of {@code request} with {@code Prefer: chargebee-telemetry=include} when not + * already set. + */ + public static Request applyResponseTelemetryPreferHeader(Request request) { + if (hasRequestHeaderIgnoreCase( + request.getHeaders(), TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)) { + return request; + } + return request.withHeader( + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER, + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_VALUE); + } + + private static boolean hasRequestHeaderIgnoreCase( + Map headers, String headerName) { + if (headers == null) { + return false; + } + for (String name : headers.keySet()) { + if (name.equalsIgnoreCase(headerName)) { + return true; + } + } + return false; + } + + private static String getHeaderValueIgnoreCase( + Map> headers, String headerName) { + for (Map.Entry> entry : headers.entrySet()) { + if (entry.getKey().equalsIgnoreCase(headerName) + && entry.getValue() != null + && !entry.getValue().isEmpty()) { + return String.join(", ", entry.getValue()); + } + } + return null; + } } diff --git a/src/test/java/com/chargebee/v4/models/BaseResponseTest.java b/src/test/java/com/chargebee/v4/models/BaseResponseTest.java index 3c6bddde..caf6cb24 100644 --- a/src/test/java/com/chargebee/v4/models/BaseResponseTest.java +++ b/src/test/java/com/chargebee/v4/models/BaseResponseTest.java @@ -92,4 +92,13 @@ void generatedListResponseHeaderLookup() { assertEquals(Collections.singletonList("req_123"), list.header("x-request-id")); assertNull(list.header("missing")); } + + @Test + @DisplayName("should look up the telemetry response header case-insensitively") + void shouldLookUpTelemetryHeaderCaseInsensitively() { + Response response = new Response(200, + httpUrlConnectionHeaders("X-Chargebee-Telemetry", "cb;time_ms=1"), "{}".getBytes()); + + assertEquals(Collections.singletonList("cb;time_ms=1"), wrap(response).header("x-chargebee-telemetry")); + } } diff --git a/src/test/java/com/chargebee/v4/telemetry/ChargebeeTelemetryHeaderParserTest.java b/src/test/java/com/chargebee/v4/telemetry/ChargebeeTelemetryHeaderParserTest.java new file mode 100644 index 00000000..9ef2e543 --- /dev/null +++ b/src/test/java/com/chargebee/v4/telemetry/ChargebeeTelemetryHeaderParserTest.java @@ -0,0 +1,135 @@ +package com.chargebee.v4.telemetry; + +import static org.junit.jupiter.api.Assertions.*; + +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +@DisplayName("ChargebeeTelemetryHeaderParser") +class ChargebeeTelemetryHeaderParserTest { + + @Test + @DisplayName("Should parse example 1 from response-header-format.md") + void shouldParseExampleOne() { + String 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"; + + Map attributes = ChargebeeTelemetryHeaderParser.parseToSpanAttributes(header); + + assertEquals(1781280400L, attributes.get("chargebee.telemetry.cb.start_time")); + assertEquals(3800L, attributes.get("chargebee.telemetry.cb.time_ms")); + assertEquals(90L, attributes.get("chargebee.telemetry.cb.res_wait_time_ms")); + assertEquals(1350L, attributes.get("chargebee.telemetry.cb.tp_time_ms")); + assertEquals(730L, attributes.get("chargebee.telemetry.tp.avalara.time_ms")); + assertEquals(620L, attributes.get("chargebee.telemetry.tp.stripe.time_ms")); + assertEquals("card", attributes.get("chargebee.telemetry.tp.stripe.pm")); + assertEquals( + List.of("consolidated_invoicing", "account_hierarchy"), + attributes.get("chargebee.telemetry.features")); + } + + @Test + @DisplayName("Should parse example 2 from response-header-format.md") + void shouldParseExampleTwo() { + String header = + "cb;start_time=@1781280900;res_wait_time_ms=120;tp_time_ms=1950;time_ms=5200, tp-stripe;pm=card;time_ms=1200, tp-avalara;time_ms=750, ft-account_hierarchy, ft-calendar_billing, ft-consolidated_invoicing"; + + Map attributes = ChargebeeTelemetryHeaderParser.parseToSpanAttributes(header); + + assertEquals(1781280900L, attributes.get("chargebee.telemetry.cb.start_time")); + assertEquals(5200L, attributes.get("chargebee.telemetry.cb.time_ms")); + assertEquals(120L, attributes.get("chargebee.telemetry.cb.res_wait_time_ms")); + assertEquals(1950L, attributes.get("chargebee.telemetry.cb.tp_time_ms")); + assertEquals(1200L, attributes.get("chargebee.telemetry.tp.stripe.time_ms")); + assertEquals(750L, attributes.get("chargebee.telemetry.tp.avalara.time_ms")); + assertEquals( + List.of("account_hierarchy", "calendar_billing", "consolidated_invoicing"), + attributes.get("chargebee.telemetry.features")); + } + + @Test + @DisplayName("Should map all RFC 9651 scalar types") + void shouldMapAllScalarTypes() { + String header = + "cb;start_time=@1781280400;time_ms=3800;ratio=99.9;desc=\"hello world\";enabled=?1;disabled=?0;payload=:aGVsbG8=:;pm=card"; + + Map attributes = ChargebeeTelemetryHeaderParser.parseToSpanAttributes(header); + + assertEquals(1781280400L, attributes.get("chargebee.telemetry.cb.start_time")); + assertEquals(3800L, attributes.get("chargebee.telemetry.cb.time_ms")); + assertEquals(99.9d, attributes.get("chargebee.telemetry.cb.ratio")); + assertEquals("hello world", attributes.get("chargebee.telemetry.cb.desc")); + assertEquals(Boolean.TRUE, attributes.get("chargebee.telemetry.cb.enabled")); + assertEquals(Boolean.FALSE, attributes.get("chargebee.telemetry.cb.disabled")); + assertEquals("aGVsbG8=", attributes.get("chargebee.telemetry.cb.payload")); + assertEquals("card", attributes.get("chargebee.telemetry.cb.pm")); + } + + @Test + @DisplayName("Should parse sf-string escapes") + void shouldParseSfStringEscapes() { + assertEquals("hello \"world\"", ChargebeeTelemetryHeaderParser.parseScalarValue("\"hello \\\"world\\\"\"")); + } + + @Test + @DisplayName("Should keep delimiters inside escaped sf-strings") + void shouldKeepDelimitersInsideEscapedSfStrings() { + String header = "cb;desc=\"a\\\"b;c\";time_ms=1"; + + Map attributes = ChargebeeTelemetryHeaderParser.parseToSpanAttributes(header); + + assertEquals("a\"b;c", attributes.get("chargebee.telemetry.cb.desc")); + assertEquals(1L, attributes.get("chargebee.telemetry.cb.time_ms")); + } + + @Test + @DisplayName("Should return empty map for blank or malformed headers") + void shouldReturnEmptyForInvalidInput() { + assertTrue(ChargebeeTelemetryHeaderParser.parseToSpanAttributes(null).isEmpty()); + assertTrue(ChargebeeTelemetryHeaderParser.parseToSpanAttributes("").isEmpty()); + assertTrue(ChargebeeTelemetryHeaderParser.parseToSpanAttributes(";;;").isEmpty()); + } + + @Test + @DisplayName("Should skip only malformed sf-integer and sf-date parameters") + void shouldSkipOnlyMalformedNumericParameters() { + String header = + "cb;start_time=@abc;frac=@1.5;big=12345678901234567890;time_ms=3800, tp-stripe;time_ms=620"; + + Map attributes = ChargebeeTelemetryHeaderParser.parseToSpanAttributes(header); + + assertFalse(attributes.containsKey("chargebee.telemetry.cb.start_time")); + assertFalse(attributes.containsKey("chargebee.telemetry.cb.frac")); + assertFalse(attributes.containsKey("chargebee.telemetry.cb.big")); + assertEquals(3800L, attributes.get("chargebee.telemetry.cb.time_ms")); + assertEquals(620L, attributes.get("chargebee.telemetry.tp.stripe.time_ms")); + } + + @Test + @DisplayName("Should accept sf-integer values up to 15 digits") + void shouldAcceptFifteenDigitIntegers() { + assertEquals(999999999999999L, ChargebeeTelemetryHeaderParser.parseScalarValue("999999999999999")); + assertEquals(-999999999999999L, ChargebeeTelemetryHeaderParser.parseScalarValue("-999999999999999")); + assertNull(ChargebeeTelemetryHeaderParser.parseScalarValue("1000000000000000")); + assertEquals(1781280400L, ChargebeeTelemetryHeaderParser.parseScalarValue("@1781280400")); + assertNull(ChargebeeTelemetryHeaderParser.parseScalarValue("@")); + } + + @Test + @DisplayName("Should treat bare parameters as true and skip only malformed parameters or members") + void shouldTreatBareParamsAsTrueAndSkipMalformedParts() { + String header = "cb;time_ms=12;cached;=5;empty=, ;orphan=1, tp-stripe;pm=card;time_ms=620"; + + Map attributes = ChargebeeTelemetryHeaderParser.parseToSpanAttributes(header); + + assertEquals(Boolean.TRUE, attributes.get("chargebee.telemetry.cb.cached")); + assertEquals(12L, attributes.get("chargebee.telemetry.cb.time_ms")); + assertFalse(attributes.containsKey("chargebee.telemetry.cb.empty")); + assertFalse(attributes.containsKey("chargebee.telemetry.cb.")); + assertEquals("card", attributes.get("chargebee.telemetry.tp.stripe.pm")); + assertEquals(620L, attributes.get("chargebee.telemetry.tp.stripe.time_ms")); + assertEquals(4, attributes.size()); + } +} diff --git a/src/test/java/com/chargebee/v4/telemetry/TelemetryExecutorTest.java b/src/test/java/com/chargebee/v4/telemetry/TelemetryExecutorTest.java index 725df2ca..d3203c7b 100644 --- a/src/test/java/com/chargebee/v4/telemetry/TelemetryExecutorTest.java +++ b/src/test/java/com/chargebee/v4/telemetry/TelemetryExecutorTest.java @@ -40,6 +40,22 @@ public CompletableFuture sendAsync(Request request) { } } + private static final class TelemetryResponseTransport implements Transport { + @Override + public Response send(Request request) { + Map> headers = new HashMap<>(); + headers.put( + "X-Chargebee-Telemetry", + List.of("cb;start_time=@1781280400;time_ms=3800, tp-stripe;pm=card;time_ms=620")); + return new Response(200, headers, "{}".getBytes()); + } + + @Override + public CompletableFuture sendAsync(Request request) { + return CompletableFuture.completedFuture(send(request)); + } + } + @Test @DisplayName("Should skip telemetry when no adapter is configured") void shouldSkipWhenNoAdapter() { @@ -137,6 +153,57 @@ public CompletableFuture sendAsync(Request request) { assertEquals("00-test-trace", allRequests.get(1).getHeaders().get("traceparent")); } + @Test + @DisplayName("Should capture X-Chargebee-Telemetry response header on success") + void shouldCaptureChargebeeTelemetryResponseHeader() { + RequestTelemetryResult[] capturedResult = new RequestTelemetryResult[1]; + + TelemetryAdapter adapter = + new TelemetryAdapter() { + @Override + public Object onRequestStart( + RequestTelemetryContext context, Map requestHeaders) { + return "span-1"; + } + + @Override + public void onRequestEnd(Object handle, RequestTelemetryResult result) { + capturedResult[0] = result; + } + }; + + ChargebeeClient client = + ChargebeeClient.builder("key_test", "acme") + .transport(new TelemetryResponseTransport()) + .retry(RetryConfig.builder().enabled(false).build()) + .telemetryAdapter(adapter) + .preferChargebeeTelemetry(true) + .build(); + + Request request = + Request.builder() + .method("POST") + .url("https://acme.chargebee.com/api/v2/invoices/consolidate") + .telemetryResource("invoice") + .telemetryOperation("consolidate") + .build(); + + client.sendWithRetry(request); + + Map telemetry = capturedResult[0].getResponseTelemetryAttributes(); + assertEquals( + "cb;start_time=@1781280400;time_ms=3800, tp-stripe;pm=card;time_ms=620", + telemetry.get("http.response.header.x-chargebee-telemetry")); + assertEquals(3800L, telemetry.get("chargebee.telemetry.cb.time_ms")); + assertEquals(620L, telemetry.get("chargebee.telemetry.tp.stripe.time_ms")); + assertEquals("card", telemetry.get("chargebee.telemetry.tp.stripe.pm")); + + // Existing adapters see the same end attributes as before this feature. + assertEquals( + java.util.Collections.singletonMap(TelemetryAttributeKeys.HTTP_RESPONSE_STATUS_CODE, 200), + capturedResult[0].getEndAttributes()); + } + @Test @DisplayName("Should capture chargebee-* request headers and exclude the PII origin family") void shouldCaptureChargebeeRequestHeaders() { @@ -160,6 +227,7 @@ public void onRequestEnd(Object handle, RequestTelemetryResult result) {} .transport(new RecordingTransport()) .retry(RetryConfig.builder().enabled(false).build()) .telemetryAdapter(adapter) + .preferChargebeeTelemetry(true) .build(); Request request = @@ -249,6 +317,7 @@ public CompletableFuture sendAsync(Request transportRequest) { }) .retry(RetryConfig.builder().enabled(false).build()) .telemetryAdapter(adapter) + .preferChargebeeTelemetry(true) .build(); assertThrows(APIException.class, () -> client.sendWithRetry(request)); @@ -362,4 +431,178 @@ public void onRequestEnd(Object handle, RequestTelemetryResult result) {} logger.setUseParentHandlers(previousUseParent); } } + + @Test + @DisplayName("Should send Prefer chargebee-telemetry=include when preferChargebeeTelemetry is true") + void shouldSendPreferHeaderWhenOptedIn() { + RecordingTransport transport = new RecordingTransport(); + TelemetryAdapter adapter = + new TelemetryAdapter() { + @Override + public Object onRequestStart( + RequestTelemetryContext context, Map requestHeaders) { + return "span-1"; + } + + @Override + public void onRequestEnd(Object handle, RequestTelemetryResult result) {} + }; + + ChargebeeClient client = + ChargebeeClient.builder("key_test", "acme") + .transport(transport) + .retry(RetryConfig.builder().enabled(false).build()) + .telemetryAdapter(adapter) + .preferChargebeeTelemetry(true) + .build(); + + Request request = + Request.builder() + .method("GET") + .url("https://acme.chargebee.com/api/v2/customers") + .telemetryResource("customer") + .telemetryOperation("list") + .build(); + + client.sendWithRetry(request); + + assertEquals(1, transport.requests.size()); + assertEquals( + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_VALUE, + transport.requests.get(0).getHeaders().get(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)); + } + + @Test + @DisplayName("Should not override an existing Prefer request header") + void shouldNotOverrideExistingPreferHeader() { + RecordingTransport transport = new RecordingTransport(); + TelemetryAdapter adapter = + new TelemetryAdapter() { + @Override + public Object onRequestStart( + RequestTelemetryContext context, Map requestHeaders) { + return "span-1"; + } + + @Override + public void onRequestEnd(Object handle, RequestTelemetryResult result) {} + }; + + ChargebeeClient client = + ChargebeeClient.builder("key_test", "acme") + .transport(transport) + .retry(RetryConfig.builder().enabled(false).build()) + .telemetryAdapter(adapter) + .preferChargebeeTelemetry(true) + .build(); + + Request request = + Request.builder() + .method("GET") + .url("https://acme.chargebee.com/api/v2/customers") + .header("Prefer", "respond-async") + .telemetryResource("customer") + .telemetryOperation("list") + .build(); + + client.sendWithRetry(request); + + assertEquals("respond-async", transport.requests.get(0).getHeaders().get("Prefer")); + } + + @Test + @DisplayName("Should not send Prefer by default when telemetry adapter is configured") + void shouldNotSendPreferByDefault() { + RecordingTransport transport = new RecordingTransport(); + TelemetryAdapter adapter = + new TelemetryAdapter() { + @Override + public Object onRequestStart( + RequestTelemetryContext context, Map requestHeaders) { + return "span-1"; + } + + @Override + public void onRequestEnd(Object handle, RequestTelemetryResult result) {} + }; + + ChargebeeClient client = + ChargebeeClient.builder("key_test", "acme") + .transport(transport) + .retry(RetryConfig.builder().enabled(false).build()) + .telemetryAdapter(adapter) + .build(); + + Request request = + Request.builder() + .method("GET") + .url("https://acme.chargebee.com/api/v2/customers") + .telemetryResource("customer") + .telemetryOperation("list") + .build(); + + client.sendWithRetry(request); + + assertFalse(transport.requests.get(0).getHeaders().containsKey("Prefer")); + } + + @Test + @DisplayName("Should not send Prefer when preferChargebeeTelemetry is false") + void shouldNotSendPreferWhenDisabled() { + RecordingTransport transport = new RecordingTransport(); + TelemetryAdapter adapter = + new TelemetryAdapter() { + @Override + public Object onRequestStart( + RequestTelemetryContext context, Map requestHeaders) { + return "span-1"; + } + + @Override + public void onRequestEnd(Object handle, RequestTelemetryResult result) {} + }; + + ChargebeeClient client = + ChargebeeClient.builder("key_test", "acme") + .transport(transport) + .retry(RetryConfig.builder().enabled(false).build()) + .telemetryAdapter(adapter) + .preferChargebeeTelemetry(false) + .build(); + + Request request = + Request.builder() + .method("GET") + .url("https://acme.chargebee.com/api/v2/customers") + .telemetryResource("customer") + .telemetryOperation("list") + .build(); + + client.sendWithRetry(request); + + assertFalse(transport.requests.get(0).getHeaders().containsKey("Prefer")); + } + + @Test + @DisplayName("Should not send Prefer when telemetry adapter is not configured") + void shouldNotSendPreferWhenNoAdapter() { + RecordingTransport transport = new RecordingTransport(); + ChargebeeClient client = + ChargebeeClient.builder("key_test", "acme") + .transport(transport) + .retry(RetryConfig.builder().enabled(false).build()) + .build(); + + Request request = + Request.builder() + .method("GET") + .url("https://acme.chargebee.com/api/v2/customers") + .telemetryResource("customer") + .telemetryOperation("list") + .build(); + + client.sendWithRetry(request); + + assertFalse(transport.requests.get(0).getHeaders().containsKey("Prefer")); + } } diff --git a/src/test/java/com/chargebee/v4/telemetry/TelemetrySupportTest.java b/src/test/java/com/chargebee/v4/telemetry/TelemetrySupportTest.java index ec983cd2..70fa9de2 100644 --- a/src/test/java/com/chargebee/v4/telemetry/TelemetrySupportTest.java +++ b/src/test/java/com/chargebee/v4/telemetry/TelemetrySupportTest.java @@ -7,6 +7,7 @@ import com.chargebee.v4.transport.Request; import com.chargebee.v4.transport.Response; import java.util.HashMap; +import java.util.List; import java.util.Map; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -14,6 +15,50 @@ @DisplayName("TelemetrySupport") class TelemetrySupportTest { + @Test + @DisplayName("Should promote X-Chargebee-Telemetry response header to end span attributes") + void shouldBuildResponseHeaderSpanAttributes() { + Map> headers = new HashMap<>(); + headers.put( + "X-Chargebee-Telemetry", + List.of( + "cb;start_time=@1781280400;time_ms=3800, tp-stripe;pm=card;time_ms=620, ft-account_hierarchy")); + + Map attributes = TelemetrySupport.buildResponseHeaderSpanAttributes(headers); + + assertEquals( + "cb;start_time=@1781280400;time_ms=3800, tp-stripe;pm=card;time_ms=620, ft-account_hierarchy", + attributes.get("http.response.header.x-chargebee-telemetry")); + assertEquals(1781280400L, attributes.get("chargebee.telemetry.cb.start_time")); + assertEquals(3800L, attributes.get("chargebee.telemetry.cb.time_ms")); + assertEquals(620L, attributes.get("chargebee.telemetry.tp.stripe.time_ms")); + assertEquals("card", attributes.get("chargebee.telemetry.tp.stripe.pm")); + assertEquals(List.of("account_hierarchy"), attributes.get("chargebee.telemetry.features")); + assertFalse(attributes.containsKey("http.response.header.content-type")); + } + + @Test + @DisplayName("Should omit telemetry attributes when response header is absent") + void shouldOmitTelemetryAttributesWhenHeaderAbsent() { + Map attributes = + TelemetrySupport.buildResponseHeaderSpanAttributes(new HashMap<>()); + + assertFalse(attributes.containsKey("http.response.header.x-chargebee-telemetry")); + assertFalse(attributes.containsKey("chargebee.telemetry.cb.time_ms")); + } + + @Test + @DisplayName("Should emit raw header only when parsing fails") + void shouldEmitRawOnlyWhenParsingFails() { + Map> headers = new HashMap<>(); + headers.put("X-Chargebee-Telemetry", List.of("cb;=missing_key")); + + Map attributes = TelemetrySupport.buildResponseHeaderSpanAttributes(headers); + + assertEquals("cb;=missing_key", attributes.get("http.response.header.x-chargebee-telemetry")); + assertFalse(attributes.containsKey("chargebee.telemetry.cb.time_ms")); + } + @Test @DisplayName("Should promote chargebee-* headers and exclude the PII origin family") void shouldBuildRequestHeaderSpanAttributes() { @@ -61,4 +106,44 @@ void shouldSetErrorTypeFromChargebeeApiErrorType() { assertEquals("resource_not_found", attributes.get(TelemetryAttributeKeys.CHARGEBEE_ERROR_CODE)); assertFalse(attributes.containsValue("404")); } + + @Test + @DisplayName("Should add Prefer chargebee-telemetry=include when not already set") + void shouldApplyResponseTelemetryPreferHeader() { + Map headers = new HashMap<>(); + TelemetrySupport.applyResponseTelemetryPreferHeader(headers); + + assertEquals( + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_VALUE, + headers.get(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)); + } + + @Test + @DisplayName("Should not override an existing Prefer request header") + void shouldNotOverrideExistingPreferHeader() { + Map headers = new HashMap<>(); + headers.put("prefer", "respond-async"); + + TelemetrySupport.applyResponseTelemetryPreferHeader(headers); + + assertEquals("respond-async", headers.get("prefer")); + assertFalse(headers.containsKey(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)); + } + + @Test + @DisplayName("Should add Prefer to immutable request copies") + void shouldApplyResponseTelemetryPreferHeaderToRequest() { + Request request = + Request.builder() + .method("GET") + .url("https://acme.chargebee.com/api/v2/customers") + .build(); + + Request updated = TelemetrySupport.applyResponseTelemetryPreferHeader(request); + + assertEquals( + TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_VALUE, + updated.getHeaders().get(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)); + assertFalse(request.getHeaders().containsKey(TelemetryAttributeKeys.CHARGEBEE_TELEMETRY_PREFER_HEADER)); + } }