--- title: Export storefront traces description: >- Learn how to monitor and analyze request traces from your Hydrogen storefront using trace exports. The trace data helps you identify performance bottlenecks, debug production issues, and optimize your app based on real user traffic. source_url: html: 'https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports' md: 'https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md' --- ExpandOn this page * [Sampling and delivery](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#sampling-and-delivery) * [Configure trace exports](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#configure-trace-exports) * [Troubleshooting](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#troubleshooting) * [Trace types](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#trace-types) # Export storefront traces Plus Trace exports are available only to stores on a [Shopify Plus plan](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plus-plan). Trace exports let you send a sample of your request traces to a supported HTTP endpoint for analysis. This helps you monitor performance and debug complex request flows in production. Traces are exported in OpenTelemetry JSON format. Tip Trace exports are intended for sampling production traffic. To log complete requests, use [log drains](https://shopify.dev/docs/storefronts/headless/hydrogen/logging) instead. *** ## Sampling and delivery Trace exports use a sampling rate to control what percentage of traces are sent. Currently this is set at \~5% but subject to change. If an export fails, then Shopify retries sending the trace data several times over a short period. Caution Delivery isn't guaranteed. If your endpoint is unavailable during the retry window, then those traces might be dropped. *** ## Configure trace exports To configure trace exports: 1. Set up an HTTP endpoint to receive OpenTelemetry trace data in OTLP/HTTP format 2. From your Shopify admin, under **Sales channels**, click **Hydrogen**. 3. On the **Hydrogen storefront** page, click **Storefront settings**. 4. On the **Storefront settings** page, click **Integrations**. 5. On the **Integrations settings** page, click **Connect an observability drain** and select **HTTP**. 6. Enter your trace export endpoint URL and any required authentication headers. 7. Click **Save**. After you save the configuration, sampled traces start flowing to your endpoint. It may take a few minutes, and you'll need to generate traffic on your storefront before traces appear. *** ## Troubleshooting If you don't see traces after 15 minutes of traffic, then check your endpoint configuration and confirm that your endpoint is receiving and processing trace data. *** ## Trace types The trace export integration captures several types of traces. Shopify provides the following telemetry data: * [Primary request traces](#primary-request-traces) * [Cache request traces](#cache-request-traces) * [Storefront API request traces](#storefront-api-request-traces) * [Third-party request traces](#third-party-request-traces) ### Primary request traces Records the initial incoming request to your Hydrogen storefront. Primary request traces include high-level timing and metadata for each sampled request. #### Example exported trace Sample primary request trace data exported in the OpenTelemetry JSON format. ```json { "resourceSpans": [{ "resource": { "attributes": [ { "key": "service.name", "value": {"stringValue": "oxygen"} }, ] }, "scopeSpans": [{ "spans": [{ "spanId": "3e5f6a7b8c9d", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "name": "GET /products/123", "kind": 2, "startTimeUnixNano": "1645567489000000000", "endTimeUnixNano": "1645567489100000000", "attributes": [ { "key": "request.type", "value": {"stringValue": "request"} }, { "key": "http.method", "value": {"stringValue": "GET"} }, { "key": "http.path", "value": {"stringValue": "/products/123"} }, { "key": "http.status_code", "value": {"intValue": 200} }, { "key": "http.host", "value": {"stringValue": "example.com"} }, { "key": "http.uri", "value": {"stringValue": "/products/123?query=test"} }, { "key": "client.country", "value": {"stringValue": "CA"} }, { "key": "client.device_type", "value": {"stringValue": "desktop"} }, { "key": "client.region_code", "value": {"stringValue": "ON"} }, { "key": "client.request_user_agent", "value": {"stringValue": "Mozilla/5.0..."} }, { "key": "shop.id", "value": {"intValue": 789} }, { "key": "storefront.id", "value": {"intValue": 123456} } ] }] }] }] } ``` #### Fields | Field | Description | | - | - | | `resourceSpans` | Array containing resource and span data in OpenTelemetry format. | | `resource.attributes` | Metadata about the service generating the spans (service.name). | | `scopeSpans` | Array containing instrumentation scope and associated spans. | | `spans` | Array of individual span objects containing trace data. | | `traceId` | A unique identifier for the entire trace (16 byte hex string). | | `spanId` | A unique identifier for this specific request span. | | `name` | The request method and URI path. | | `startTimeUnixNano` | When the request started (nanoseconds since Unix epoch as string). | | `endTimeUnixNano` | When the request completed (nanoseconds since Unix epoch as string). | | `kind` | The type of span (2 = SERVER). | #### Attributes | Attribute | Description | | - | - | | `http.method` | The HTTP request method used. | | `http.path` | The request path. | | `http.uri` | The full request URI. | | `http.host` | The request hostname. | | `http.status_code` | The HTTP response status code. | | `client.country` | The client's country code. | | `client.device_type` | The type of client device making the request. | | `client.region_code` | The client's region code. | | `client.request_user_agent` | The client's user agent string. | | `request.type` | Always `request` for primary request traces. | | `shop.id` | The shop ID as an integer. | | `storefront.id` | The application handle (app\_handle) for the storefront as an integer. | ### Cache request traces Records internal cache operations during request processing. #### Example exported trace Sample cache request trace data exported in the OpenTelemetry JSON format. ```json { "resourceSpans": [{ "resource": { "attributes": [ { "key": "service.name", "value": {"stringValue": "oxygen"} }, ] }, "scopeSpans": [{ "spans": [{ "spanId": "7a8b9c0d1e2f", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "parentSpanId": "3e5f6a7b8c9d", "name": "CACHE [HIT] query ProductDetails", "kind": 2, "startTimeUnixNano": "1645567489010000000", "endTimeUnixNano": "1645567489015000000", "attributes": [ { "key": "request.type", "value": {"stringValue": "cache_api"} }, { "key": "cache.status", "value": {"stringValue": "hit"} }, { "key": "status.code", "value": {"intValue": 200} }, { "key": "cache.query.type", "value": {"stringValue": "query"} }, { "key": "cache.query.url", "value": {"stringValue": "https://{shop}.myshopify.com/api/2024-01/graphql.json"} }, { "key": "cache.query.name", "value": {"stringValue": "ProductDetails"} }, { "key": "cache.query.payload", "value": {"stringValue": "{\"query\":\"query ProductDetails {...}\"}"} } ] }] }] }] } ``` #### Attributes | Attribute | Description | | - | - | | `request.type` | Always `cache_api` for cache request traces. | | `cache.status` | The cache status (hit, miss, etc.). | | `status.code` | The response status code. | | `cache.query.type` | The type of GraphQL operation (query, mutation). | | `cache.query.url` | The URL of the GraphQL endpoint being cached. | | `cache.query.name` | The name of the GraphQL operation. | | `cache.query.payload` | The GraphQL query payload. | ### Storefront API request traces Records requests to Shopify's Storefront API during request processing. #### Example exported trace Sample Storefront API sub-request trace data exported in the OpenTelemetry JSON format. ```json { "resourceSpans": [{ "resource": { "attributes": [ { "key": "service.name", "value": {"stringValue": "oxygen"} } ] }, "scopeSpans": [{ "spans": [{ "spanId": "9f1e2d3c4b5a", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "parentSpanId": "3e5f6a7b8c9d", "name": "SFAPI query ProductDetails", "kind": 2, "startTimeUnixNano": "1645567489020000000", "endTimeUnixNano": "1645567489070000000", "attributes": [ { "key": "request.type", "value": {"stringValue": "sfapi_subrequest"} }, { "key": "http.host", "value": {"stringValue": "{shop}.myshopify.com"} }, { "key": "http.method", "value": {"stringValue": "POST"} }, { "key": "http.path", "value": {"stringValue": "/api/2024-01/graphql.json"} }, { "key": "http.status_code", "value": {"intValue": 200} }, { "key": "http.uri", "value": {"stringValue": "/api/2024-01/graphql.json"} }, { "key": "sfapi.query.name", "value": {"stringValue": "ProductDetails"} }, { "key": "sfapi.query.type", "value": {"stringValue": "query"} } ] }] }] }] } ``` #### Attributes | Attribute | Description | | - | - | | `request.type` | Always `sfapi_subrequest` for Storefront API request traces. | | `http.host` | The hostname of the Storefront API endpoint. | | `http.method` | The HTTP request method used. | | `http.path` | The request path to the Storefront API. | | `http.status_code` | The HTTP response status code. | | `http.uri` | The request URI. | | `sfapi.query.name` | The name of the GraphQL operation being performed. | | `sfapi.query.type` | The type of GraphQL operation (query or mutation). | ### Third-party request traces Records outbound requests to third-party services during request processing. #### Example exported trace Sample third party sub-request trace data exported in the OpenTelemetry JSON format. ```json { "resourceSpans": [{ "resource": { "attributes": [ { "key": "service.name", "value": {"stringValue": "oxygen"} } ] }, "scopeSpans": [{ "spans": [{ "spanId": "a1b2c3d4e5f6", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "parentSpanId": "3e5f6a7b8c9d", "name": "POST /api/v1/data", "kind": 2, "startTimeUnixNano": "1645567489030000000", "endTimeUnixNano": "1645567489080000000", "attributes": [ { "key": "request.type", "value": {"stringValue": "subrequest"} }, { "key": "http.host", "value": {"stringValue": "api.example.com"} }, { "key": "http.method", "value": {"stringValue": "POST"} }, { "key": "http.path", "value": {"stringValue": "/api/v1/data"} }, { "key": "http.status_code", "value": {"intValue": 200} }, { "key": "http.uri", "value": {"stringValue": "/api/v1/data"} } ] }] }] }] } ``` #### Attributes | Attribute | Description | | - | - | | `request.type` | Always `subrequest` for third-party request traces. | | `http.method` | The HTTP method used for the third-party request. | | `http.path` | The request path to the third-party service. | | `http.uri` | The request URI. | | `http.host` | The hostname of the third-party service. | | `http.status_code` | The HTTP status code returned by the third-party service. | *** * [Sampling and delivery](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#sampling-and-delivery) * [Configure trace exports](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#configure-trace-exports) * [Troubleshooting](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#troubleshooting) * [Trace types](https://shopify.dev/docs/storefronts/headless/hydrogen/trace-exports.md#trace-types)