配置选项

ClickStack 的各个组件均提供以下配置选项：

如果使用 All in One、HyperDX Only 或 Local Mode，只需通过环境变量传入所需设置，例如：

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

如果使用 Docker Compose 部署指南，可以通过 .env 文件修改设置。

或者，也可以直接在 docker-compose.yaml 文件中显式覆盖这些设置，例如：

示例：

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... 其他设置

你可以使用 --set 参数来自定义设置，例如：

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

也可以编辑 values.yaml。如需获取默认配置值：

helm show values hyperdx/hdx-oss-v2 > values.yaml

示例配置：

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

ClickStack UI 依赖用户为每一种可观测性数据类型/支柱定义一个数据源：

• Logs
• Traces
• Metrics
• Sessions

此配置可在应用内的 Team Settings -> Sources 中完成，下面以日志为例：

创建这些数据源时，每个数据源都至少需要指定一张表，以及一组供 HyperDX 查询数据的列。

如果使用 ClickStack 附带的默认 OpenTelemetry (OTel) schema，则每个数据源所需的这些列都可以自动推断出来。如果修改 schema或使用自定义 schema，则用户需要指定并更新这些映射。

以下是每个数据源可用的设置：

可以为日志和链路追踪数据源注册 materialized view，使符合条件的聚合查询从预聚合视图而非源表获取结果。有关创建和注册视图的说明，请参阅“Materialized views”。

每个已注册的视图均包含以下设置：

选择目标表后，大多数设置会根据视图的 schema 自动推断。

元数据 materialized views 可加速过滤器的字段发现和自动补全。可在日志和链路追踪数据源上配置。

高亮属性和高亮 trace 属性都可以在日志和 trace 数据源上配置。

• 高亮属性是查看日志或 span 详情时，为每条日志或 span 显示的列或表达式。
• 高亮 trace 属性是从某个 trace 中的每条日志或 span 查询出的列或表达式，并显示在 trace 瀑布图上方。

这些属性定义在数据源配置中，可以是任意 SQL 表达式。如果 SQL 表达式返回的值是 URL 格式，该属性会显示为链接。空值不会显示。

每个属性均使用以下设置进行配置：

例如，这个链路追踪数据源已配置了一个高亮属性和一个高亮 trace 属性：

点击日志或 span 后，这些属性会显示在侧边面板中：

点击某个属性后，可以选择将该属性用作搜索值。如果在属性配置中提供了可选的 Lucene 表达式，搜索时将使用 Lucene 表达式而不是 SQL 表达式。

要在 ClickStack 中启用完整的跨数据源关联，您必须为日志、链路追踪、指标和会话配置关联来源。这样，HyperDX 就能将相关数据关联起来，并在渲染事件时提供更丰富的上下文。

• Logs：可与链路追踪和指标关联。
• Traces：可与日志、会话和指标关联。
• Metrics：可与日志关联。
• Sessions：可与链路追踪关联。

配置这些关联后，即可启用多项功能。例如，HyperDX 可以在显示 trace 的同时呈现相关日志，或突出显示与会话相关联的指标异常。

例如，下面是已配置关联来源的日志数据源：

• HYPERDX_API_KEY

  • 默认值： None (必填)
  • 说明： 用于 HyperDX API 的身份验证密钥。
  • 指导：
  • 遥测和日志功能必需
  • 在本地开发环境中，可使用任意非空值
  • 在生产环境中，请使用安全且唯一的密钥
  • 创建账户后，可从 Team Settings 页面获取

• HYPERDX_LOG_LEVEL

  • 默认值： info
  • 说明： 设置日志详细程度。
  • 可选项： debug, info, warn, error
  • 建议：
  • 使用 debug 进行详细故障排查
  • 使用 info 用于正常运行
  • 在生产环境中使用 warn 或 error 以减少日志量

• HYPERDX_API_PORT

  • 默认值： 8000
  • 说明： HyperDX API 服务器使用的端口。
  • 指导：
  • 确保该端口在主机上可用
  • 如果存在端口冲突，请更改此端口
  • 必须与 API 客户端配置中的端口保持一致

• HYPERDX_APP_PORT

  • 默认值： 8000
  • 说明： HyperDX 前端应用使用的端口。
  • 指导：
  • 确保此端口在主机上可用
  • 如果发生端口冲突，请更改该端口
  • 必须可通过浏览器访问

• HYPERDX_APP_URL

  • 默认值： http://localhost
  • 说明： 前端应用的基础 URL。
  • 指导：
  • 在生产环境中将其设置为你的域名
  • 包含协议 (http/https)
  • 不要包含末尾斜杠

• MONGO_URI

  • 默认值： mongodb://db:27017/hyperdx
  • 说明： MongoDB 连接字符串。
  • 指导：
  • 在使用 Docker 的本地开发环境中，可使用默认值
  • 在生产环境中，请使用安全的连接字符串
  • 如果需要，请包含身份验证信息
  • 示例：mongodb://user:pass@host:port/db

• MINER_API_URL

  • 默认值： http://miner:5123
  • 说明： 日志模式挖掘服务的 URL。
  • 指导：
  • 在使用 Docker 的本地开发环境中使用默认值
  • 在生产环境中，将其设置为你的 miner 服务 URL
  • 必须可从 API 服务访问

• FRONTEND_URL

  • 默认值： http://localhost:3000
  • 说明： 前端应用的 URL。
  • 建议：
  • 本地开发时使用默认值
  • 在生产环境中设置为您的域名
  • API 服务必须能够访问该地址

• OTEL_SERVICE_NAME

  • 默认值： hdx-oss-api
  • 说明： OpenTelemetry 插桩的服务名称。
  • 指导：
  • 为 HyperDX 服务使用便于识别的名称。适用于 HyperDX 自行插桩的场景。
  • 有助于在遥测数据中识别 HyperDX 服务

• NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT

  • 默认值： http://localhost:4318
  • 说明： OpenTelemetry collector 端点。
  • 指导：
  • 适用于 HyperDX 自行埋点。
  • 本地开发时使用默认值
  • 在生产环境中，将其设置为你的 collector URL
  • 必须可从你的 HyperDX 服务访问

• USAGE_STATS_ENABLED

  • 默认值： true
  • 说明： 用于控制是否收集使用统计信息。
  • 指导：
  • 设置为 false 可禁用使用情况跟踪
  • 适用于对隐私较为敏感的部署
  • 默认为 true，以便更好地改进产品

• IS_OSS

  • 默认值： true
  • 说明： 表示是否以 OSS 模式运行。
  • 指导：
  • 开源部署时，保持为 true
  • Enterprise 部署时，设置为 false
  • 会影响功能可用性

• IS_LOCAL_MODE

  • 默认值： false
  • 说明： 指示是否以本地模式运行。
  • 建议：
  • 本地开发时设置为 true
  • 会禁用某些生产环境功能
  • 适用于测试和开发

• EXPRESS_SESSION_SECRET

  • 默认值： hyperdx is cool 👋
  • 说明： 用于 Express 会话管理的密钥。
  • 指南：
  • 请在生产环境中更改
  • 使用高强度的随机字符串
  • 妥善保密并安全存储

• ENABLE_SWAGGER

  • 默认值： false
  • 说明： 用于启用或禁用 Swagger API 文档。
  • 指导：
  • 设置为 true 以启用 API 文档
  • 适用于开发和测试环境
  • 在生产环境中禁用

• BETA_CH_OTEL_JSON_SCHEMA_ENABLED

  • 默认值： false
  • 说明： 在 HyperDX 中启用对 JSON type 的 Beta 支持。另请参阅 OTEL_AGENT_FEATURE_GATE_ARG，以在 OTel collector 中启用 JSON 支持。
  • 指导：
    • 这会启用一项 Beta 功能。对于典型的可观测性 workloads，不建议使用 JSON 类型的 schema。有关两者的对比及各自适用场景，请参阅 Map vs JSON type。
    • 将其设置为 true，即可在 ClickStack UI 中启用 JSON 支持。

更多详情，请参见 "ClickStack OpenTelemetry Collector"。

• CLICKHOUSE_ENDPOINT

  • 默认值： 独立镜像时为 无 (必填) 。如果是 All-in-one 或 Docker Compose 发行版，则会设置为集成的 ClickHouse 实例。
  • 说明： 用于将遥测数据导出到 ClickHouse 实例的 HTTPS URL。
  • 指导：
    • 必须是包含端口的完整 HTTPS 端点 (例如：https://clickhouse.example.com:8443)
    • collector 向 ClickHouse 发送数据时必需

• CLICKHOUSE_USER

  • 默认值： default
  • 说明： 用于向 ClickHouse 实例进行身份验证的用户名。
  • 指导：
    • 确保该用户具有 INSERT 和 CREATE TABLE 权限
    • 建议为摄取创建专用用户

• CLICKHOUSE_PASSWORD

  • 默认值： 无 (启用身份验证时必填)
  • 说明： 指定 ClickHouse 用户的密码。
  • 指导：
    • 如果该用户账户设置了密码，则此项必填
    • 在生产环境部署中通过 secrets 安全存储

• HYPERDX_LOG_LEVEL

  • 默认值： info
  • 说明： collector 的日志详细级别。
  • 指导：
    • 可接受的值包括 debug、info、warn、error
    • 在故障排查期间使用 debug

• OPAMP_SERVER_URL

  • 默认值： 独立镜像时为 无 (必填) 。如果是 All-in-one 或 Docker Compose 发行版，则指向已部署的 HyperDX 实例。
  • 说明： 用于管理 collector 的 OpAMP server URL (例如 HyperDX 实例) 。默认端口为 4320。
  • 指导：
    • 必须指向你的 HyperDX 实例
    • 启用动态配置和安全摄取
    • 如果省略，则会禁用安全摄取，除非指定了 OTLP_AUTH_TOKEN 值。

• OTLP_AUTH_TOKEN

  • 默认值： 无。仅用于独立镜像。
  • 说明： 允许指定 OTLP 身份验证令牌。如果设置了该值，则所有通信都需要此 Bearer 令牌。
  • 指导：
    • 如果在生产环境中使用独立 collector 镜像，建议设置此项。

• HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

  • 默认值： default
  • 说明： collector 将遥测数据写入的 ClickHouse database。
  • 指导：
    • 如果使用自定义 database 名称，请设置此项
    • 确保指定用户对该 database 具有访问权限

• OTEL_AGENT_FEATURE_GATE_ARG

  • 默认值： <empty string>
  • 说明： 在 collector 中启用功能开关。如果设置为 --feature-gates=clickhouse.json，则会在 collector 中启用 JSON type 的 Beta 支持，并确保使用该类型创建 schema。另请参见 BETA_CH_OTEL_JSON_SCHEMA_ENABLED 以在 HyperDX 中启用 JSON 支持。
  • 指导：
    • 这会启用一项 Beta 功能。对于典型的可观测性 workload，不建议使用 JSON-typed schemas。有关对比以及各自适用场景，请参见 Map vs JSON type。
    • 设置为 --feature-gates=clickhouse.json，以使用 JSON type 创建新表。

ClickStack 开源版附带了一个面向多 TB 规模的默认 ClickHouse 配置，但用户也可以根据自身工作负载自由修改和优化。

要有效调优 ClickHouse，你需要理解一些关键存储概念，例如 parts、分区、分片和副本，以及 合并 如何在写入时发生。我们建议你先了解 主索引、稀疏二级索引 和数据跳过索引的基础知识，以及管理数据生命周期的相关方法，例如使用生存时间 (TTL) 进行生命周期管理。

ClickStack 支持 schema 自定义——你可以修改列类型、提取新字段 (例如从日志中提取) 、应用编解码器和字典，并使用 projections 加速查询。

此外，materialized views 可用于在摄取期间转换或过滤数据，前提是数据写入该视图的源表，并且应用程序从目标表读取数据。materialized views 也可用于在 ClickStack 中以原生方式加速查询。

更多详情请参阅 ClickHouse 关于 schema 设计、索引策略和数据管理最佳实践的文档——其中大部分内容都可直接应用于 ClickStack 部署。