> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sample logs, traces and metrics

> Explore ClickHouse Observability with a sample dataset of logs, sessions, traces and metrics

Explore ClickHouse Observability using sample logs, sessions, traces, and metrics from an e-commerce store. Both deployment modes use the same dataset and investigation workflow.

Before you begin, complete the [fully managed getting started guide](https://clickhouse.com/docs/clickstack/observability/getting-started.md) or the [self-managed getting started guide](https://clickhouse.com/docs/clickstack/self-configured/getting-started/managed.md).

**1. Configure your connection**

Choose your deployment and set the following variables in the terminal where you will load the sample data.

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Open **Team Settings → Data** and find **Managed Telemetry**. Under **OpenTelemetry Collector**, use the **URL** option to copy the OTLP HTTP endpoint and API key. Select **Reveal key** to view the full values.
>
> Set the base endpoint without a signal path such as `/v1/logs`. Include the `Bearer` prefix in the authorization value:
>
> ```shell theme={null}
> export CLICKSTACK_OTLP_ENDPOINT='<your-managed-otlp-http-endpoint>'
> export CLICKSTACK_AUTHORIZATION='Bearer <your-api-key>'
> ```
>
> You do not need to deploy a collector for this example.

> [tab] Self-managed
>
> You need a running ClickStack OpenTelemetry collector connected to your ClickHouse Cloud service. Follow the [Ingesting with OpenTelemetry guide](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md#self-managed) to configure the connection, or the [deployment guide](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md) to start a collector.
>
> Set the collector's OTLP HTTP endpoint, reachable from the machine running the upload command. Use the base URL without a signal path such as `/v1/logs`:
>
> ```shell theme={null}
> export CLICKSTACK_OTLP_ENDPOINT='http://<collector-host>:4318'
> export CLICKSTACK_AUTHORIZATION=''
> ```
>
> If the collector requires authentication, set `CLICKSTACK_AUTHORIZATION` to its receiver token. For a ClickStack collector secured with `OTLP_AUTH_TOKEN`, use that value without a `Bearer` prefix. Leave the value empty for a receiver that does not require authentication. Do not use your ClickHouse database password here.

**2. Download sample data**

In order to populate the UI with sample data, download the following file:

[Sample data](https://storage.googleapis.com/hyperdx/sample.tar.gz)

```shell theme={null}
# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# or
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz
```

This file contains example logs, metrics, and traces from our public [OpenTelemetry demo](https://github.com/ClickHouse/opentelemetry-demo) - a simple e-commerce store with microservices. Copy this file to a directory of your choosing.

**3. Load sample data**

Run the following commands in **Bash** from the directory containing `sample.tar.gz`. They send the sample data to the endpoint configured above, adding an authorization header only when one is required.

```bash theme={null}
set -eo pipefail

auth_headers=()
if [ -n "${CLICKSTACK_AUTHORIZATION:-}" ]; then
  auth_headers=(-H "Authorization: ${CLICKSTACK_AUTHORIZATION}")
fi

for filename in $(tar -tf sample.tar.gz); do
  endpoint="${CLICKSTACK_OTLP_ENDPOINT%/}/v1/${filename%.json}"
  echo "loading ${filename%.json}"
  tar -xOf sample.tar.gz "$filename" | while read -r line; do
    printf '%s\n' "$line" | curl --fail-with-body -sS -X POST "$endpoint" \
      -H "Content-Type: application/json" \
      "${auth_headers[@]}" \
      --data-binary @-
  done
done
```

This simulates OTLP log, trace, and metric sources sending data. In production, these sources may be application SDKs, agents, or OpenTelemetry Collectors.

In the ClickHouse Cloud console, select your service and open ClickHouse Observability.

Return to [Search](https://clickhouse.com/docs/clickstack/observability/features/search.md) to view the loaded data. Select the **Logs** source and a time range that includes the sample events' timestamps. The screenshot below shows sample logs arriving in **Live Tail**:

![Search showing loaded sample logs from the e-commerce demo services](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-search.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=02b4a0abb1cfa08aeebcf917d54985e3)

Data loading will take a few minutes. Allow for the load to be completed before progressing to the next steps.

**4. Explore sessions**

Suppose we have reports that our users are experiencing issues paying for goods. We can view their experience using session replay.

Select **Client Sessions** from the left menu and set a time range that includes the loaded sample sessions.

![Client Sessions showing sample sessions with an error count highlighted](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-sessions.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=657511973445668b4c14ba2c351032d3)

This view lists sessions from the demo store, including anonymous sessions and sessions identified by an email address.

Some sessions have a nonzero error count. In this example, the highlighted session has one error.

Select the highlighted session to open its replay. Use the play button at the bottom of the player to watch the session.

![Session replay showing the OpenTelemetry demo storefront and navigation events](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-replay.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=ac13d3d2e8ead558fec58ee8483178f2)

The replay shows the user navigating the site, adding items to their cart. Feel free to skip to later in the session where they attempt to complete a payment.

> [!TIP]
>
> Error events are marked in red in the event list.

Scroll to the bottom of the event list on the left. The highlighted `POST /api/checkout` request returned HTTP `500`, with a console error recorded at the same time.

![Session replay highlighting the failed POST request to /api/checkout and associated console error](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-checkout-error.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=0c09b1d8e1310cc6d4fb78a1bf5171df)

Select the failed `POST /api/checkout` event to inspect the request and its trace.

**5. Explore traces**

Open the **Trace** tab to see the distributed trace, including related spans and correlated logs.

![Trace waterfall showing the checkout request with its spans, correlated logs, and errors](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-trace.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=b02856ca2ab2625e6b14a8f85cebb08b)

Scroll down the trace and select the `oteldemo.PaymentService/Charge` span in the `checkout` service.

![Selected payment request span showing an expired-card error in its attributes](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-payment-span.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=eadcca2c247b5aa1d80bf48da2f0a341)

In the **Overview** tab, inspect **Top Level Attributes**. The `StatusCode` is `Error`, and the `StatusMessage` indicates that the credit card has expired.

![Overview attributes showing an Error status and a message that the credit card has expired](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-span-attributes.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=e463947552117bef92a4a1bc7913a847)

In the trace, select the `payment` error log beneath the payment service span. Its row has a log icon, distinguishing it from the error span event. In **Overview**, the log's **Body** confirms that the credit card has expired. The attributes identify the `payment` service and an `error` severity, providing context alongside the trace.

![Correlated payment error log showing the expired-card message and log attributes](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-correlated-log.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=f6161746f1164137e59caa2630086214)

We've traced this failed checkout to a payment request rejected because the credit card had expired.

**6. Explore logs**

To investigate other payment failures, return to [Search](https://clickhouse.com/docs/clickstack/observability/features/search.md).

Select **Logs** as the source and choose `payment` under the **ServiceName** filter. Use a time range that includes the session you investigated.

![Search filtered to the payment service showing expired-card and Visa cache-full errors alongside successful transactions](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-payment-logs.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=d1f930177bdb725a170f4ee6646755c4)

The results include the expired-card error from the session we investigated, as well as repeated `Visa cache full: cannot add new item.` errors. To see when errors occur across the payment service, chart these error logs over time.

**7. Chart payment errors**

Open **Chart Explorer**, select **Time Series**, and choose **Logs** as the data source. Select **Count of Events** as the aggregation.

In **Where**, select **Lucene** and enter the following filter:

```text theme={null}
SeverityText:"error" ServiceName:"payment"
```

Set a time range covering the sample data and select **Run**.

![Chart Explorer counting payment service error logs over time using a Lucene filter](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-sample-data-payment-errors-chart.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=d06718f65bb719ef73cd936c0531c451)

The chart shows the number of matching error logs in each time interval. It includes all errors from the `payment` service, including expired-card and cache-full errors. These are log-event counts, not a count of unique failed payments.