ClickHouse/clickhouse-docs-embeddings huggingface dataset:
Alerts with ClickStack

To remove an alert, open the edit dialog for the associated search or chart, then select **Remove Alert**.
In the example below, the `Remove Alert` button will remove the alert from the chart.

## Common alert scenarios[​](#common-alert-scenarios "Direct link to Common alert scenarios")

Here are a few common alert scenarios you can use HyperDX for:

**Errors:** We recommend setting up alerts for the default
`All Error Events` and `HTTP Status >= 400` saved searches to be notified when
excess errors occur.

**Slow Operations:** You can set up a search for slow operations (e.g.,
`duration:>5000`) and then alert when there are too many slow operations
occurring.

**User Events:** You can also set up alerts for customer-facing teams to be
notified when new users sign up or a critical user action is performed.

- [Types of alerts](#types-of-alerts)
  - [1. Search alerts](#search-alerts)- [2. Dashboard chart alerts](#dashboard-alerts)- [Adding a webhook](#add-webhook)
    - [Service type integrations](#integrations)- [Managing alerts](#managing-alerts)
      - [Deleting an alert](#deleting-alerts)- [Common alert scenarios](#common-alert-scenarios)

Was this page helpful?
Configuration Options

attributes. Yes Yes `SpanAttributes`| `Span Events Expression` Expression to extract span events. Typically a `Nested` type column. This allows rendering of exception stack traces with supported language SDKs. Yes Yes `Events`| `Implicit Column Expression` Column used for full-text search if no field is specified (Lucene-style). Typically the log body. Yes Yes `SpanName`| `Highlighted Attributes` Expressions or columns displayed when opening span details. Expressions returning URLs will be shown as links. No No –|  |  |  |  |  | | --- | --- | --- | --- | --- | | `Highlighted Trace Attributes` Expressions or columns extracted from each span in a trace, displayed above the trace waterfall. Expressions returning URLs will be shown as links. No No – | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Configuration Options

ClickStack supports [schema customization](/docs/use-cases/observability/schema-design) - you may modify column types, extract new fields (e.g. from logs), apply codecs and dictionaries, and accelerate queries using projections.

Additionally, materialized views can be used to [transform or filter data during ingestion](/docs/use-cases/observability/schema-design#materialized-columns), provided that data is written to the source table of the view and the application reads from the target table. Materialized views can also be used to [accelerate queries natively](/docs/use-cases/observability/clickstack/materialized_views) in ClickStack.

For more details, refer to ClickHouse documentation on schema design, indexing strategies, and data management best practices - most of which apply directly to ClickStack deployments.

- [Settings for open source distributions](#modifying-settings)
  - [Docker](#docker)- [Docker Compose](#docker-compose)- [Helm](#helm)- [ClickStack UI (HyperDX) application](#hyperdx)
    - [Data source settings](#datasource-settings)- [Correlated sources](#correlated-sources)- [Application configuration settings](#application-configuration-settings)- [OpenTelemetry collector](#otel-collector)- [ClickHouse](#clickhouse)

Was this page helpful?
Deployment Options

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/deployment/index.md)

ClickStack provides multiple deployment options to suit various use cases.

Each of the deployment options are summarized below. The [Getting Started Guide](/docs/use-cases/observability/clickstack/getting-started) specifically demonstrates options 1 and 2. They're included here for completeness.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Name Description Suitable For Limitations Example Link|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Managed ClickStack ClickHouse and ClickStack UI (HyperDX) hosted in ClickHouse Cloud. Production deployments, demos, proof-of-concepts None [Managed](/docs/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud)| All-in-One Single Docker container with all ClickStack components bundled. Non-production deployments, demos, proof of concepts Not recommended for production [All-in-One](/docs/use-cases/observability/clickstack/deployment/all-in-one)| Helm Official Helm chart for Kubernetes-based deployments. Supports ClickHouse Cloud and production scaling. Production deployments on Kubernetes Kubernetes knowledge required, customization via Helm [Helm](/docs/use-cases/observability/clickstack/deployment/helm)| Docker Compose Deploy each ClickStack component individually via Docker Compose. Local testing, proof of concepts, production on single server, BYO ClickHouse No fault tolerance, requires managing multiple containers [Docker Compose](/docs/use-cases/observability/clickstack/deployment/docker-compose)| HyperDX Only Use HyperDX independently with your own ClickHouse and schema. Existing ClickHouse users, custom event pipelines No ClickHouse included, user must manage ingestion and schema [HyperDX Only](/docs/use-cases/observability/clickstack/deployment/hyperdx-only)| Local Mode Only Runs entirely in the browser with local storage. No backend or persistence. Demos, debugging, dev with HyperDX No auth, no persistence, no alerting, single-user only [Local Mode Only](/docs/use-cases/observability/clickstack/deployment/local-mode-only) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Was this page helpful?
Docker Compose

- `OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json'` - enables support in the OTel collector, ensuring schemas are created using the JSON type.
- `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` (ClickStack Open Source only) - enables support in the ClickStack UI application, allowing JSON data to be queried.

To set these, modify the relevant services in the `docker-compose.yml`:

```
  app:
    image: ${IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    ports:
      - ${HYPERDX_API_PORT}:${HYPERDX_API_PORT}
      - ${HYPERDX_APP_PORT}:${HYPERDX_APP_PORT}
    environment:
      BETA_CH_OTEL_JSON_SCHEMA_ENABLED: true # enable JSON
      FRONTEND_URL: ${HYPERDX_APP_URL}:${HYPERDX_APP_PORT}
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_API_PORT: ${HYPERDX_API_PORT}
    # truncated for brevity

  otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      OTEL_AGENT_FEATURE_GATE_ARG: '--feature-gates=clickhouse.json' # enable JSON
      CLICKHOUSE_ENDPOINT: 'tcp://ch-server:9000?dial_timeout=10s' 
      # truncated for brevity
```

- [Suitable for](#suitable-for)- [Deployment steps](#deployment-steps)
    - [Clone the repo](#clone-the-repo)- [Navigate to the HyperDX UI](#navigate-to-hyperdx-ui)- [Complete connection details](#complete-connection-details)- [Modifying compose settings](#modifying-settings)
      - [Configuring the OpenTelemetry collector](#configuring-collector)- [Using ClickHouse Cloud](#using-clickhouse-cloud)- [JSON type support](#json-type-support)

Was this page helpful?
Local Mode Only

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/deployment/oss/local-mode-only.md)

Similar to the [all-in-one image](/docs/use-cases/observability/clickstack/deployment/docker-compose), this comprehensive Docker image bundles all ClickStack components:

- **ClickHouse**
- **HyperDX**
- **OpenTelemetry (OTel) collector** (exposing OTLP on ports `4317` and `4318`)
- **MongoDB** (for persistent application state)

**However, user authentication is disabled for this distribution of HyperDX**

### Suitable for[​](#suitable-for "Direct link to Suitable for")

- Demos
- Debugging
- Development where HyperDX is used

## Deployment steps[​](#deployment-steps "Direct link to Deployment steps")

  

Deploy with Docker

### Deploy with Docker[​](#deploy-with-docker "Direct link to Deploy with Docker")

Local mode deploys the HyperDX UI on port 8080.

```
docker run -p 8080:8080 clickhouse/clickstack-local:latest
```

Navigate to the HyperDX UI

### Navigate to the HyperDX UI[​](#navigate-to-hyperdx-ui "Direct link to Navigate to the HyperDX UI")

Visit <http://localhost:8080> to access the HyperDX UI.

**You won't be prompted to create a user, as authentication isn't enabled in this deployment mode.**

Connect to your own external ClickHouse cluster e.g. ClickHouse Cloud.

Create a source, retain all default values, and complete the `Table` field with the value `otel_logs`. All other settings should be auto-detected, allowing you to click `Save New Source`.

## JSON type support[​](#json-type-support "Direct link to JSON type support")

Beta feature. [Learn more.](/docs/beta-and-experimental-features#beta-features)

Beta Feature - not production ready

JSON type support in **ClickStack** is a **beta feature**. While the JSON type itself is production-ready in ClickHouse 25.3+, its integration within ClickStack is still under active development and may have limitations, change in the future, or contain bugs.

ClickStack has beta support for the [JSON type](/docs/interfaces/formats/JSON) from version `2.0.4`.

For the benefits of this type see [Benefits of the JSON type](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector#benefits-json-type).

In order to enable support for the JSON type you must set the following environment variables:

- `OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json'` - enables support in the OTel collector, ensuring schemas are created using the JSON type.
- `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` (ClickStack Open Source only) - enables support in the ClickStack UI application, allowing JSON data to be queried.

For the local mode only image, users only need to set the `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` parameter e.g.

```
docker run -e BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true -p 8080:8080 clickhouse/clickstack-local:latest
```

- [Suitable for](#suitable-for)- [Deployment steps](#deployment-steps)
    - [Deploy with Docker](#deploy-with-docker)- [Navigate to the HyperDX UI](#navigate-to-hyperdx-ui)- [JSON type support](#json-type-support)

Was this page helpful?
Open Source Deployment Options

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/deployment/oss/index.md)

Open Source ClickStack provides multiple deployment options to suit various use cases.

Each of the deployment options are summarized below. The [Open Source Getting Started Guide](/docs/use-cases/observability/clickstack/getting-started/oss) specifically demonstrates options 1, included here for completeness.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Name Description Suitable For Limitations Example Link|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | All-in-One Single Docker container with all ClickStack components bundled. Non-production deployments, demos, proof of concepts Not recommended for production [All-in-One](/docs/use-cases/observability/clickstack/deployment/all-in-one)| Helm Official Helm chart for Kubernetes-based deployments. Supports ClickHouse Cloud and production scaling. Production deployments on Kubernetes Kubernetes knowledge required, customization via Helm [Helm](/docs/use-cases/observability/clickstack/deployment/helm)| Docker Compose Deploy each ClickStack component individually via Docker Compose. Local testing, proof of concepts, production on single server, BYO ClickHouse No fault tolerance, requires managing multiple containers [Docker Compose](/docs/use-cases/observability/clickstack/deployment/docker-compose)| HyperDX Only Use HyperDX independently with your own ClickHouse and schema. Existing ClickHouse users, custom event pipelines No ClickHouse included, user must manage ingestion and schema [HyperDX Only](/docs/use-cases/observability/clickstack/deployment/hyperdx-only)| Local Mode Only Runs entirely in the browser with local storage. No backend or persistence. Demos, debugging, dev with HyperDX No auth, no persistence, no alerting, single-user only [Local Mode Only](/docs/use-cases/observability/clickstack/deployment/local-mode-only)| ClickHouse Embedded ClickStack UI bundled directly into the ClickHouse server binary. No additional components required. Trying ClickStack, exploring existing ClickHouse data, demos No alerting, no dashboard/search persistence, no customizable query settings, no event patterns [ClickHouse Embedded](/docs/use-cases/observability/clickstack/deployment/clickhouse-embedded) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Was this page helpful?
title_wip

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/getting-started/index.md)

ClickStack can be deployed in several ways depending on your operational preferences and requirements:

- [Managed ClickStack](/docs/use-cases/observability/clickstack/getting-started/managed) - The **easiest and simplest** way to get started, deploying **Managed ClickStack** on **ClickHouse Cloud**.
- [Open-Source ClickStack](/docs/use-cases/observability/clickstack/getting-started/oss) - For those of you who wish to run a fully open source architecture yourself.

Was this page helpful?
Getting Started with Managed ClickStack

Navigate to the ClickStack UI

## Navigate to the ClickStack UI[​](#navigate-to-clickstack-ui-cloud "Direct link to Navigate to the ClickStack UI")

Select 'Launch ClickStack' to access the ClickStack UI (HyperDX). You will automatically authenticated and redirected.

- OpenTelemetry- Vector

Data sources will be pre-created for any OpenTelemetry data.

If you're using Vector, you will need to create your own data sources. You will be prompted to create one on your first login. Below we show an example configuration for a logs data source.

This configuration assumes an Nginx-style schema with a `time_local` column used as the timestamp. This should be, where possible, the timestamp column declared in the primary key. **This column is mandatory**.

We also recommend updating the `Default SELECT` to explicitly define which columns are returned in the logs view. If additional fields are available, such as service name, log level, or a body column, these can also be configured. The timestamp display column can also be overridden if it differs from the column used in the table's primary key and configured above.

In the example above, a `Body` column doesn't exist in the data. Instead, it is defined using a SQL expression that reconstructs an Nginx log line from the available fields.

For other possible options, see the [configuration reference](/docs/use-cases/observability/clickstack/config).

Once created, you should be directed to the search view where you can immediately begin exploring your data.

  

And that’s it — you’re all set. 🎉

Go ahead and explore ClickStack: start searching logs and traces, see how logs, traces, and metrics correlate in real time, build dashboards, explore service maps, uncover event deltas and patterns, and set up alerts to stay ahead of issues.

Next Steps

## Next Steps[​](#next-steps "Direct link to Next Steps")

Record default credentials

If you haven't recorded your default credentials during the above steps, navigate to the service and select `Connect`, recording the password and HTTP/native endpoints. Store these admin credentials securely, which can be reused in further guides.

To perform tasks such as provisioning new users or adding further data sources, see the [deployment guide for Managed ClickStack](/docs/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud#additional-tasks).

- [Signup to ClickHouse Cloud](#signup-to-clickhouse-cloud)- [Setup ingestion](#setup-ingestion)
    - [Start a collector](#start-a-collector)- [Configure existing collectors](#configure-existing-collectors)- [Start ingestion (optional)](#start-ingestion-create-new)- [Demo data](#demo-data)- [Create a database and table](#create-database-and-tables)- [Navigate to the ClickStack UI](#navigate-to-clickstack-ui-cloud)- [Next Steps](#next-steps)

Was this page helpful?
Remote Demo Dataset

### Replaying sessions[​](#replaying-sessions "Direct link to Replaying sessions")

Sessions can be replayed by pressing the ▶️ button. Switching between `Highlighted` and `All Events` allows varying degrees of span granularity, with the former highlighting key events and errors.

If we scroll to the bottom of the spans we can see a `500` error associated with `/api/checkout`. Selecting the ▶️ button for this specific span moves the replay to this point in the session, allowing us to confirm the customer's experience - payment seems to simply not work with no error rendered.

Selecting the span we can confirm this was caused by an internal error. By clicking the `Trace` tab and scrolling though the connected spans, we're able to confirm the customer indeed was a victim of our cache issue.

This demo walks through a real-world incident involving failed payments in an e-commerce app, showing how ClickStack helps uncover root causes through unified logs, traces, metrics, and session replays - explore our [other getting started guides](/docs/use-cases/observability/clickstack/sample-datasets) to dive deeper into specific features.

- [Demo scenario](#demo-scenario)- [OpenTelemetry Demo](#otel-demo)
    - [Demo Architecture](#demo-architecture)- [Demo steps](#demo-steps)
      - [Connect to the demo server](#connect-to-the-demo-server)- [Modify the sources](#modify-sources)- [Adjust the time frame](#adjust-the-timeframe)- [Filter to errors](#filter-to-errors)- [Identify the error patterns](#identify-error-patterns)- [Explore an error pattern](#explore-error-pattern)- [Explore the infrastructure](#explore-the-infrastructure)- [Explore a trace](#explore-a-trace)- [Searching traces](#searching-traces)- [Explore infrastructure for a trace](#explore-infrastructure-for-a-trace)- [Event deltas for faster resolution](#event-deltas-for-faster-resolution)- [Using charts for more context](#using-charts-for-more-context)- [Exploring metrics more context](#exploring-metrics-for-more-context)- [Using sessions](#using-sessions)- [Replaying sessions](#replaying-sessions)

Was this page helpful?
title_wip

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/ingesting-data/index.md)

Managed and Open Source ClickStack provides multiple ways to ingest observability data into your ClickHouse instance. Whether you're collecting logs, metrics, traces, or session data, you can use the OpenTelemetry (OTel) collector as a unified ingestion point or leverage platform-specific integrations for specialized use cases.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Section Description|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Overview](/docs/use-cases/observability/clickstack/ingesting-data/overview) Introduction to data ingestion methods and architecture|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Ingesting data with OpenTelemetry](/docs/use-cases/observability/clickstack/ingesting-data/opentelemetry) For users using OpenTelemetry and looking to quickly integrate with ClickStack|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | [OpenTelemetry collector](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector) Advanced details for the ClickStack OpenTelemetry collector|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | [Ingesting data with Vector](/docs/use-cases/observability/clickstack/ingesting-data/vector) For users using Vector and looking to quickly integrate with ClickStack|  |  |  |  | | --- | --- | --- | --- | | [Tables and Schemas](/docs/use-cases/observability/clickstack/ingesting-data/schemas) Overview of the ClickHouse tables and their schemas used by ClickStack|  |  | | --- | --- | | [Language SDKs](/docs/use-cases/observability/clickstack/sdks) ClickStack SDKs for instrumenting programming languages and collecting telemetry data | | | | | | | | | | | | | |

Was this page helpful?