Export storefront traces
Trace exports are available only to stores on a 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.
Trace exports are intended for sampling production traffic. To log complete requests, use log drains instead.
Anchor to Sampling and deliverySampling 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.
Delivery isn't guaranteed. If your endpoint is unavailable during the retry window, then those traces might be dropped.
Anchor to Configure trace exportsConfigure trace exports
To configure trace exports:
- Set up an HTTP endpoint to receive OpenTelemetry trace data in OTLP/HTTP format
- From your Shopify admin, under Sales channels, click Hydrogen.
- On the Hydrogen storefront page, click Storefront settings.
- On the Storefront settings page, click Integrations.
- On the Integrations settings page, click Connect an observability drain and select HTTP.
- Enter your trace export endpoint URL and any required authentication headers.
- 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.
Anchor to TroubleshootingTroubleshooting
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.
Anchor to Trace typesTrace types
The trace export integration captures several types of traces. Shopify provides the following telemetry data:
- Primary request traces
- Cache request traces
- Storefront API request traces
- Third-party request traces
Anchor to Primary request tracesPrimary request traces
Records the initial incoming request to your Hydrogen storefront. Primary request traces include high-level timing and metadata for each sampled request.
Anchor to Example exported traceExample exported trace
Sample primary request trace data exported in the OpenTelemetry JSON format.
Anchor to FieldsFields
| 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). |
Anchor to AttributesAttributes
| 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. |
Anchor to Cache request tracesCache request traces
Records internal cache operations during request processing.
Anchor to Example exported traceExample exported trace
Sample cache request trace data exported in the OpenTelemetry JSON format.
Anchor to AttributesAttributes
| 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. |
Anchor to Storefront API request tracesStorefront API request traces
Records requests to Shopify's Storefront API during request processing.
Anchor to Example exported traceExample exported trace
Sample Storefront API sub-request trace data exported in the OpenTelemetry JSON format.
Anchor to AttributesAttributes
| 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). |
Anchor to Third-party request tracesThird-party request traces
Records outbound requests to third-party services during request processing.
Anchor to Example exported traceExample exported trace
Sample third party sub-request trace data exported in the OpenTelemetry JSON format.
Anchor to AttributesAttributes
| 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. |