|
| 1 | +# Integrations |
| 2 | + |
| 3 | +Since version 1.1.0, this library supports an `integrations` feature that facilitates integration with external systems that require specific telemetry configurations. Integrations are preconfigured patches that automatically handle complex setup tasks, such as context propagation, span linking, and sampling decisions. |
| 4 | + |
| 5 | +> [!IMPORTANT] |
| 6 | +> Integrations are configuration patches applied sequentially to your telemetry configuration. Each integration can override or extend existing settings, so the order in which you apply them matters. |
| 7 | +
|
| 8 | +- [Integrations](#integrations) |
| 9 | + - [What are Integrations?](#what-are-integrations) |
| 10 | + - [How to Use Integrations](#how-to-use-integrations) |
| 11 | + - [Available Integrations](#available-integrations) |
| 12 | + |
| 13 | +## What are Integrations? |
| 14 | + |
| 15 | +Integrations are functions that return configuration patches for specific external systems. Instead of manually configuring context propagation, span links, and sampling strategies for each integration point, you can use these pre-built integrations to handle the complexity automatically. |
| 16 | + |
| 17 | +Key characteristics: |
| 18 | + |
| 19 | +- **Pre-configured**: Each integration encapsulates best practices for a specific external system |
| 20 | +- **Composable**: Can be applied at the global or per-action level |
| 21 | +- **Sequential**: Applied in order, with later integrations potentially overriding earlier ones |
| 22 | +- **Type-safe**: Full TypeScript support with documented options |
| 23 | + |
| 24 | +## How to Use Integrations |
| 25 | + |
| 26 | +### Global Configuration |
| 27 | + |
| 28 | +Apply integrations to all runtime actions by including them in your global telemetry configuration: |
| 29 | + |
| 30 | +```ts |
| 31 | +// telemetry.{js|ts} |
| 32 | +import { defineTelemetryConfig } from "@adobe/aio-lib-telemetry"; |
| 33 | +import { commerceEvents } from "@adobe/aio-lib-telemetry/integrations"; |
| 34 | + |
| 35 | +const telemetryConfig = defineTelemetryConfig((params, isDev) => { |
| 36 | + return { |
| 37 | + sdkConfig: { |
| 38 | + // Your OpenTelemetry SDK configuration |
| 39 | + }, |
| 40 | + integrations: [commerceEvents()], |
| 41 | + }; |
| 42 | +}); |
| 43 | + |
| 44 | +export { telemetryConfig }; |
| 45 | +``` |
| 46 | + |
| 47 | +### Per-Action Configuration |
| 48 | + |
| 49 | +Override global integrations for specific actions: |
| 50 | + |
| 51 | +> [!WARNING] |
| 52 | +> Integrations are applied on top of your base configuration. Some options you set manually may be overridden by the integrations you apply. |
| 53 | +
|
| 54 | +```ts |
| 55 | +// actions/my-webhook-handler/index.js |
| 56 | +import { instrumentEntrypoint } from "@adobe/aio-lib-telemetry"; |
| 57 | +import { commerceWebhooks } from "@adobe/aio-lib-telemetry/integrations"; |
| 58 | +import { telemetryConfig } from "../../telemetry"; |
| 59 | + |
| 60 | +export const main = instrumentEntrypoint( |
| 61 | + async function webhooksHandler(params) { |
| 62 | + // Your webhook handler code |
| 63 | + }, |
| 64 | + { |
| 65 | + ...telemetryConfig, |
| 66 | + // This overrides the global integrations |
| 67 | + integrations: [commerceWebhooks()], |
| 68 | + }, |
| 69 | +); |
| 70 | +``` |
| 71 | + |
| 72 | +## Available Integrations |
| 73 | + |
| 74 | +### Adobe Commerce Events |
| 75 | + |
| 76 | +**Import**: `commerceEvents` from `@adobe/aio-lib-telemetry/integrations` |
| 77 | + |
| 78 | +**Use Case**: Runtime actions that receive [Adobe Commerce Events](https://developer.adobe.com/commerce/extensibility/events/) |
| 79 | + |
| 80 | +#### What it Does |
| 81 | + |
| 82 | +Adobe Commerce Events are asynchronous event notifications sent from Commerce to your runtime actions. This integration: |
| 83 | + |
| 84 | +1. **Extracts trace context** from the event's `data._metadata` field |
| 85 | +2. **Creates span links** to connect your action's trace with the Commerce event trace |
| 86 | +3. **Skips context propagation** since events are asynchronous (not part of the same execution trace) |
| 87 | +4. **Adds trace ID attribute** (`commerce.traceid`) for backends that don't fully support span links |
| 88 | + |
| 89 | +#### Usage |
| 90 | + |
| 91 | +```ts |
| 92 | +import { commerceEvents } from "@adobe/aio-lib-telemetry/integrations"; |
| 93 | + |
| 94 | +const telemetryConfig = defineTelemetryConfig((params, isDev) => { |
| 95 | + return { |
| 96 | + integrations: [commerceEvents()], |
| 97 | + }; |
| 98 | +}); |
| 99 | +``` |
| 100 | + |
| 101 | +#### Event Structure |
| 102 | + |
| 103 | +Commerce Events include trace context in the `_metadata` field: |
| 104 | + |
| 105 | +```json |
| 106 | +{ |
| 107 | + "data": { |
| 108 | + "_metadata": { |
| 109 | + "traceparent": "00-traceId-spanId-01", |
| 110 | + "tracestate": "..." |
| 111 | + } |
| 112 | + |
| 113 | + // Event payload |
| 114 | + } |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +The integration automatically extracts and processes the trace information. |
| 119 | + |
| 120 | +#### When to Use |
| 121 | + |
| 122 | +- Runtime actions registered as Commerce event subscribers |
| 123 | +- Actions that need to correlate their telemetry with Commerce event processing |
| 124 | +- Scenarios where you want to link asynchronous event handling to the originating Commerce operation |
| 125 | + |
| 126 | +### Adobe Commerce Webhooks |
| 127 | + |
| 128 | +**Import**: `commerceWebhooks` from `@adobe/aio-lib-telemetry/integrations` |
| 129 | +**Use Case**: Runtime actions that receive [Adobe Commerce Webhooks](https://developer.adobe.com/commerce/extensibility/webhooks/) |
| 130 | + |
| 131 | +#### What it Does |
| 132 | + |
| 133 | +Adobe Commerce Webhooks are HTTP requests sent from Commerce to your runtime actions. This integration: |
| 134 | + |
| 135 | +1. **Extracts trace context** from HTTP headers following W3C Trace Context specification |
| 136 | +2. **Handles sampling decisions** intelligently based on Commerce's configuration |
| 137 | +3. **Creates new traces** when Commerce sends non-sampled context (configurable) |
| 138 | +4. **Preserves log correlation** by linking to the Commerce trace even when creating new traces |
| 139 | + |
| 140 | +#### Usage |
| 141 | + |
| 142 | +```ts |
| 143 | +import { commerceWebhooks } from "@adobe/aio-lib-telemetry/integrations"; |
| 144 | + |
| 145 | +// With default configuration |
| 146 | +const telemetryConfig = defineTelemetryConfig((params, isDev) => { |
| 147 | + return { |
| 148 | + integrations: [commerceWebhooks()], |
| 149 | + }; |
| 150 | +}); |
| 151 | + |
| 152 | +// With custom configuration |
| 153 | +const telemetryConfig = defineTelemetryConfig((params, isDev) => { |
| 154 | + return { |
| 155 | + integrations: [ |
| 156 | + commerceWebhooks({ |
| 157 | + ensureSampling: false, // Disable automatic sampling override |
| 158 | + }), |
| 159 | + ], |
| 160 | + }; |
| 161 | +}); |
| 162 | +``` |
| 163 | + |
| 164 | +#### Configuration Options |
| 165 | + |
| 166 | +##### `ensureSampling` |
| 167 | + |
| 168 | +**Type**: `boolean` |
| 169 | +**Default**: `true` |
| 170 | +**Since**: 1.1.0 |
| 171 | + |
| 172 | +Controls whether runtime actions should always create traces, regardless of Commerce's subscription configuration. |
| 173 | + |
| 174 | +**Background**: Commerce integrations can be configured with: |
| 175 | + |
| 176 | +- **Trace subscriptions**: Full distributed tracing (sampled traces) |
| 177 | +- **Log-only subscriptions**: No tracing, only logs (non-sampled traces) |
| 178 | + |
| 179 | +With log-only subscriptions, Commerce propagates trace context marked as non-sampled (for log correlation). By default, OpenTelemetry's ParentBased sampler would cause your runtime action to also not sample, resulting in no trace data. |
| 180 | + |
| 181 | +**When `true` (default)**: |
| 182 | + |
| 183 | +- Runtime actions create their own sampled trace when Commerce's trace is non-sampled |
| 184 | +- Links to Commerce's trace for log correlation |
| 185 | +- Inherits Commerce's trace normally when it's sampled |
| 186 | + |
| 187 | +**When `false`**: |
| 188 | + |
| 189 | +- Runtime action tracing depends on Commerce's subscription configuration |
| 190 | +- No traces exported when Commerce uses log-only subscriptions |
| 191 | + |
| 192 | +**Example**: |
| 193 | + |
| 194 | +```ts |
| 195 | +// Ensure traces are always created (recommended) |
| 196 | +commerceWebhooks({ ensureSampling: true }); |
| 197 | + |
| 198 | +// Follow Commerce's sampling decision |
| 199 | +commerceWebhooks({ ensureSampling: false }); |
| 200 | +``` |
| 201 | + |
| 202 | +#### When to Use |
| 203 | + |
| 204 | +- Runtime actions registered as Commerce webhook endpoints |
| 205 | +- Actions that need distributed tracing with Commerce operations |
| 206 | +- Scenarios where you want flexible control over trace sampling |
0 commit comments