Otel integration

CHANGELOG.md

@@ -1,3 +1,12 @@
+### v4.23.0 (2026-06-30)
+* * *
+
+### New Features
+* Added an optional telemetry adapter hook for tracing Chargebee API calls via OpenTelemetry (or any APM). Configure it via the `telemetryAdapter` client option (or `Environment::setTelemetryAdapter`). When unconfigured, the SDK skips all telemetry work — no behavior change for existing integrations.
+* Each API call emits one CLIENT span (`chargebee.{resource}.{operation}`) with OpenTelemetry HTTP semantic-convention attributes plus `chargebee.*` attributes. Adapters may inject W3C trace context (`traceparent`) into outbound request headers for distributed tracing.
+* Exposed the `TelemetryAdapter`, `RequestTelemetryContext`, `RequestTelemetryResult`, `RequestTelemetryError` types, the `TelemetrySupport` helpers, and the `TelemetryAttributeKeys` constants under the `Chargebee\Telemetry` namespace.
+
+
 ### v4.22.0 (2026-06-12)
 * * *
 ### New Resources:

README.md

@@ -153,6 +153,103 @@ $chargebee = new ChargebeeClient(options: [
 
 ```
 
+### Telemetry (OpenTelemetry)
+
+Optional. Pass a `telemetryAdapter` when you want Chargebee API calls traced in your observability stack (Datadog, Splunk, Honeycomb, Jaeger, etc.). OpenTelemetry is not bundled with `chargebee/chargebee-php` — install and configure it in your app, implement `TelemetryAdapter`, and wire it on the client.
+
+The SDK builds standardized span attributes (`startAttributes`, `endAttributes`) following the stable [OpenTelemetry HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) (`url.full`, `http.request.method`, `http.response.status_code`, `server.address`, `error.type`) plus Chargebee-specific `chargebee.*` attributes — use them as-is so spans render correctly in your APM and stay consistent across SDKs.
+
+> **Note:** `url.full` intentionally omits the query string (it carries only scheme, host, and path) to avoid leaking potentially sensitive query parameters into traces. This is a deliberate, cross-SDK PII-safety choice.
+
+Spans are named `chargebee.{resource}.{operation}` (e.g. `chargebee.subscription.create`).
+
+When no adapter is configured, the SDK skips all telemetry work — zero overhead for existing integrations.
+
+#### Trace shape
+
+The SDK emits **one `CLIENT` span per API call**, covering the full lifecycle. Retries reuse the same span — `onRequestStart` runs once before the retry loop and `onRequestEnd` runs once after the final outcome.
+
+```
+inbound request span
+└── chargebee.subscription.create   ← parented to caller, propagates to Chargebee
+        └── (Chargebee-side spans)
+```
+
+> If you separately enable HTTP auto-instrumentation (e.g. an OpenTelemetry PHP agent on Guzzle), it will create an **additional transport-level HTTP span as a sibling** of the Chargebee span. For the cleanest trace where `chargebee.{resource}.{operation}` is the single propagating span, leave HTTP auto-instrumentation off for Chargebee calls.
+
+#### OpenTelemetry setup
+
+OpenTelemetry is not bundled — install it in your app:
+
+```sh
+composer require open-telemetry/sdk open-telemetry/exporter-otlp
+```
+
+Configure OpenTelemetry at app startup (tracer provider, exporter, propagator), then pass your adapter:
+
+```php
+use Chargebee\ChargebeeClient;
+use Chargebee\Telemetry\RequestTelemetryContext;
+use Chargebee\Telemetry\RequestTelemetryResult;
+use Chargebee\Telemetry\TelemetryAdapter;
+use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
+use OpenTelemetry\API\Trace\SpanInterface;
+use OpenTelemetry\API\Trace\SpanKind;
+use OpenTelemetry\API\Trace\StatusCode;
+use OpenTelemetry\API\Trace\TracerInterface;
+
+class OtelTelemetryAdapter implements TelemetryAdapter
+{
+    public function __construct(private readonly TracerInterface $tracer) {}
+
+    public function onRequestStart(RequestTelemetryContext $context, array &$requestHeaders): mixed
+    {
+        $span = $this->tracer
+            ->spanBuilder($context->spanName)
+            ->setSpanKind(SpanKind::KIND_CLIENT)
+            ->setAttributes($context->startAttributes)
+            ->startSpan();
+
+        $scope = $span->activate();
+        TraceContextPropagator::getInstance()->inject($requestHeaders);
+        $scope->detach();
+
+        return $span;
+    }
+
+    public function onRequestEnd(mixed $handle, RequestTelemetryResult $result): void
+    {
+        if (!$handle instanceof SpanInterface) {
+            return;
+        }
+
+        $span = $handle;
+        $span->setAttributes($result->endAttributes);
+
+        if ($result->error !== null) {
+            $span->setStatus(StatusCode::STATUS_ERROR, $result->error->message);
+        } else {
+            $span->setStatus(StatusCode::STATUS_OK);
+        }
+
+        $span->end();
+    }
+}
+
+$tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('your-app');
+$chargebee = new ChargebeeClient([
+    'site' => '{your_site}',
+    'apiKey' => '{your_apiKey}',
+    'telemetryAdapter' => new OtelTelemetryAdapter($tracer),
+]);
+```
+
+`RequestTelemetryResult` also exposes `durationMs` if you want to record request duration on the span (e.g. `$span->setAttribute('chargebee.request.duration_ms', $result->durationMs)`).
+
+To add custom span attributes (tenant ID, correlation ID, etc.), set them in your adapter's `onRequestStart` / `onRequestEnd` — use your own namespace (e.g. `app.tenant_id`), not `chargebee.*`.
+
+Spans are exported by your own OpenTelemetry setup, so they flow to whatever backend you've configured. The Chargebee config above stays the same regardless of backend.
+
 ## License
 
 See the LICENSE file.

VERSION

@@ -1 +1 @@
-4.22.0
+4.23.0

src/Actions/AddonActions.php

@@ -61,6 +61,8 @@ public function copy(array $params, array $headers = []): CopyAddonResponse
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("copy")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -92,6 +94,8 @@ public function unarchive(string $id, array $headers = []): UnarchiveAddonRespon
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withIdempotent(true)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("unarchive")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -122,6 +126,8 @@ public function retrieve(string $id, array $headers = []): RetrieveAddonResponse
         ->withSubDomain(null)
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("retrieve")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -205,6 +211,8 @@ public function update(string $id, array $params, array $headers = []): UpdateAd
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("update")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -321,6 +329,8 @@ public function all(array $params = [], array $headers = []): ListAddonResponse
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("list")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -406,6 +416,8 @@ public function create(array $params, array $headers = []): CreateAddonResponse
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("create")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -437,6 +449,8 @@ public function delete(string $id, array $headers = []): DeleteAddonResponse
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withIdempotent(true)
+        ->withTelemetryResource("addon")
+        ->withTelemetryOperation("delete")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);

src/Actions/AddressActions.php

@@ -52,6 +52,8 @@ public function retrieve(array $params, array $headers = []): RetrieveAddressRes
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("address")
+        ->withTelemetryOperation("retrieve")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -101,6 +103,8 @@ public function update(array $params, array $headers = []): UpdateAddressRespons
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("address")
+        ->withTelemetryOperation("update")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);

src/Actions/AlertActions.php

@@ -63,6 +63,8 @@ public function applicationAlertsForSubscription(string $id, array $params = [],
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("alert")
+        ->withTelemetryOperation("applicationAlertsForSubscription")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -93,6 +95,8 @@ public function retrieve(string $id, array $headers = []): RetrieveAlertResponse
         ->withSubDomain(null)
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
+        ->withTelemetryResource("alert")
+        ->withTelemetryOperation("retrieve")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -131,6 +135,8 @@ public function update(string $id, array $params = [], array $headers = []): Upd
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("alert")
+        ->withTelemetryOperation("update")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -162,6 +168,8 @@ public function delete(string $id, array $headers = []): DeleteAlertResponse
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withIdempotent(true)
+        ->withTelemetryResource("alert")
+        ->withTelemetryOperation("delete")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -208,6 +216,8 @@ public function all(array $params = [], array $headers = []): ListAlertResponse
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("alert")
+        ->withTelemetryOperation("list")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -256,6 +266,8 @@ public function create(array $params, array $headers = []): CreateAlertResponse
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("alert")
+        ->withTelemetryOperation("create")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);

src/Actions/AlertStatusActions.php

@@ -59,6 +59,8 @@ public function alertStatusesForSubscription(string $id, array $params = [], arr
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("alertStatus")
+        ->withTelemetryOperation("alertStatusesForSubscription")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -96,6 +98,8 @@ public function alertStatusesForAlert(string $id, array $params = [], array $hea
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("alertStatus")
+        ->withTelemetryOperation("alertStatusesForAlert")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);

src/Actions/AttachedItemActions.php

@@ -55,6 +55,8 @@ public function retrieve(string $id, array $params, array $headers = []): Retrie
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("attachedItem")
+        ->withTelemetryOperation("retrieve")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -95,6 +97,8 @@ public function update(string $id, array $params, array $headers = []): UpdateAt
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("attachedItem")
+        ->withTelemetryOperation("update")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -167,6 +171,8 @@ public function all(string $id, array $params = [], array $headers = []): ListAt
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("attachedItem")
+        ->withTelemetryOperation("list")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -208,6 +214,8 @@ public function create(string $id, array $params, array $headers = []): CreateAt
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("attachedItem")
+        ->withTelemetryOperation("create")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -242,6 +250,8 @@ public function delete(string $id, array $params, array $headers = []): DeleteAt
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("attachedItem")
+        ->withTelemetryOperation("delete")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);

src/Actions/BusinessEntityActions.php

@@ -72,6 +72,8 @@ public function getTransfers(array $params = [], array $headers = []): GetTransf
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withParams($params)
+        ->withTelemetryResource("businessEntity")
+        ->withTelemetryOperation("getTransfers")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -110,6 +112,8 @@ public function createTransfers(array $params, array $headers = []): CreateTrans
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("businessEntity")
+        ->withTelemetryOperation("createTransfers")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);

src/Actions/CardActions.php

@@ -55,6 +55,8 @@ public function copyCardForCustomer(string $id, array $params, array $headers =
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("card")
+        ->withTelemetryOperation("copyCardForCustomer")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -85,6 +87,8 @@ public function retrieve(string $id, array $headers = []): RetrieveCardResponse
         ->withSubDomain(null)
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
+        ->withTelemetryResource("card")
+        ->withTelemetryOperation("retrieve")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -120,6 +124,8 @@ public function switchGatewayForCustomer(string $id, array $params, array $heade
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("card")
+        ->withTelemetryOperation("switchGatewayForCustomer")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -151,6 +157,8 @@ public function deleteCardForCustomer(string $id, array $headers = []): DeleteCa
         ->withJsonKeys($jsonKeys)
         ->withHeaders($headers)
         ->withIdempotent(true)
+        ->withTelemetryResource("card")
+        ->withTelemetryOperation("deleteCardForCustomer")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);
@@ -205,6 +213,8 @@ public function updateCardForCustomer(string $id, array $params, array $headers
         ->withHeaders($headers)
         ->withParams($params)
         ->withIdempotent(true)
+        ->withTelemetryResource("card")
+        ->withTelemetryOperation("updateCardForCustomer")
         ->build();
         $apiRequester = new APIRequester($this->httpClientFactory, $this->env);
         $respObject = $apiRequester->makeRequest($payload);