跳到主要内容
跳到主要内容

配置选项

以下是 ClickStack 各组件可用的配置选项:

修改设置

Docker

如果使用 All in OneHyperDX OnlyLocal Mode,只需通过环境变量传递所需的设置,例如:

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

Docker Compose

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

或者,可以在 docker-compose.yaml 文件中显式覆盖设置,例如:

示例:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... other settings

Helm

自定义值(可选)

您可以使用 --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

HyperDX

数据源设置

HyperDX 依赖用户为每种可观察性数据类型/支柱定义源:

  • Logs
  • Traces
  • Metrics
  • Sessions

此配置可以在应用程序中通过 Team Settings -> Sources 完成,如下所示以获取日志为例:

HyperDX Source configuration

每个源在创建时都需要至少指定一个表,以及一组允许 HyperDX 查询数据的列。

如果使用 default OpenTelemetry (OTel) schema,ClickStack 分发的这些列可以为每个源自动推导。如果 modifying the schema 或使用自定义架构,用户需要指定和更新这些映射。

备注

ClickStack 附带的 ClickHouse 默认架构是由 ClickHouse exporter for the OTel collector 创建的架构。这些列名与 OTel 官方规范文档 此处 中的相关。

以下设置适用于每个源:

日志

设置描述必需在默认架构中推导推导值
Name源名称。
Server Connection服务器连接名称。Default
DatabaseClickHouse 数据库名称。default
Table目标表名称。如果使用默认架构,则设置为 otel_logs
Timestamp Column作为主键一部分的时间戳列或表达式。TimestampTime
Default Select默认搜索结果中显示的列。Timestamp, ServiceName, SeverityText, Body
Service Name Expression服务名称的表达式或列。ServiceName
Log Level Expression日志级别的表达式或列。SeverityText
Body Expression日志消息的表达式或列。Body
Log Attributes Expression自定义日志属性的表达式或列。LogAttributes
Resource Attributes Expression资源级别属性的表达式或列。ResourceAttributes
Displayed Timestamp Column用于 UI 显示的时间戳列。ResourceAttributes
Correlated Metric Source关联的指标源(例如 HyperDX 指标)。
Correlated Trace Source关联的跟踪源(例如 HyperDX 跟踪)。
Trace Id Expression用于提取跟踪 ID 的表达式或列。TraceId
Span Id Expression用于提取跨度 ID 的表达式或列。SpanId
Implicit Column Expression用于全文搜索的列,如果没有指定字段(Lucene 风格)。通常是日志主体。Body

跟踪

设置描述必需在默认架构中推导推导值
Name源名称。
Server Connection服务器连接名称。Default
DatabaseClickHouse 数据库名称。default
Table目标表名称。如果使用默认架构,则设置为 otel_traces-
Timestamp Column作为主键一部分的时间戳列或表达式。Timestamp
TimestampTimestamp Column 的别名。Timestamp
Default Select默认搜索结果中显示的列。Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName
Duration Expression用于计算跨度持续时间的表达式。Duration
Duration Precision持续时间表达式的精度(例如,纳秒、微秒)。ns
Trace Id Expression跟踪 ID 的表达式或列。TraceId
Span Id Expression跨度 ID 的表达式或列。SpanId
Parent Span Id Expression父跨度 ID 的表达式或列。ParentSpanId
Span Name Expression跨度名称的表达式或列。SpanName
Span Kind Expression跨度类型的表达式或列(例如,客户端、服务器)。SpanKind
Correlated Log Source可选。关联的日志源(例如,HyperDX 日志)。
Correlated Session Source可选。关联的会话源。
Correlated Metric Source可选。关联的指标源(例如,HyperDX 指标)。
Status Code Expression跨度状态代码的表达式。StatusCode
Status Message Expression跨度状态消息的表达式。StatusMessage
Service Name Expression服务名称的表达式或列。ServiceName
Resource Attributes Expression资源级别属性的表达式或列。ResourceAttributes
Event Attributes Expression事件属性的表达式或列。SpanAttributes
Span Events Expression提取跨度事件的表达式。通常是 Nested 类型的列。这允许与支持的语言 SDK 渲染异常堆栈跟踪。Events
Implicit Column Expression用于全文搜索的列,如果没有指定字段(Lucene 风格)。通常是日志主体。SpanName

指标

设置描述必需在默认架构中推导推导值
Name源名称。
Server Connection服务器连接名称。Default
DatabaseClickHouse 数据库名称。default
Gauge Table存储测量类型指标的表。otel_metrics_gauge
Histogram Table存储直方图类型指标的表。otel_metrics_histogram
Sum Table存储总和类型(计数器)指标的表。otel_metrics_sum
Correlated Log Source可选。关联的日志源(例如,HyperDX 日志)。

会话

设置描述必需在默认架构中推导推导值
Name源名称。
Server Connection服务器连接名称。Default
DatabaseClickHouse 数据库名称。default
Table会话数据的目标表。目标表名称。如果使用默认架构,则设置为 hyperdx_sessions-
Timestamp Column作为主键一部分的时间戳列或表达式。TimestampTime
Log Attributes Expression从会话数据中提取日志级别属性的表达式。LogAttributes
LogAttributes用于存储日志属性的别名或字段引用。LogAttributes
Resource Attributes Expression用于提取资源级别元数据的表达式。ResourceAttributes
Correlated Trace Source可选。用于会话关联的跟踪源。
Implicit Column Expression如果未指定字段(例如,Lucene 样式查询解析),则用于全文搜索的列。Body

关联源

要在 ClickStack 中启用完全的跨源关联,用户必须为日志、跟踪、指标和会话配置关联源。这使得 HyperDX 能够关联相关数据,并在呈现事件时提供丰富的上下文。

  • Logs:可以与跟踪和指标关联。
  • Traces:可以与日志、会话和指标关联。
  • Metrics:可以与日志关联。
  • Sessions:可以与跟踪关联。

通过设置这些关联,HyperDX 可以例如在跟踪旁边呈现相关日志或显示与会话相关的指标异常。正确的配置确保统一和上下文丰富的可观察性体验。

例如,以下是配置了关联源的日志源:

HyperDX Source correlated

应用程序配置设置

HyperDX 在 ClickHouse Cloud 中

当 HyperDX 在 ClickHouse Cloud 中管理时,这些设置无法修改。

  • HYPERDX_API_KEY

    • 默认值: 无(必需)
    • 描述: HyperDX API 的身份验证密钥。
    • 指导:
    • 为遥测和日志记录所需
    • 在本地开发中,可以是任何非空值
    • 对于生产,使用安全的唯一密钥
    • 在创建帐户后可以从团队设置页面获取
  • HYPERDX_LOG_LEVEL

    • 默认值: info
    • 描述: 设置日志的详细程度级别。
    • 选项: debug, info, warn, error
    • 指导:
    • 在故障排除时使用 debug
    • 正常操作使用 info
    • 在生产中使用 warnerror 来减少日志量
  • 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 的默认值
    • 在生产环境中设置为您的挖掘服务 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 收集器端点。
    • 指导:
    • 与自我插桩的 HyperDX 相关。
    • 在本地开发时使用默认值
    • 在生产中设置为您的收集器 URL
    • 必须可以从 HyperDX 服务访问
  • USAGE_STATS_ENABLED

    • 默认值: true
    • 描述: 切换使用统计信息的收集。
    • 指导:
    • 设置为 false 以禁用使用跟踪
    • 对于隐私敏感的部署很有用
    • 默认值为 true 以改善产品
  • IS_OSS

    • 默认值: true
    • 描述: 表示是否在 OSS 模式下运行。
    • 指导:
    • 对于开源部署保持为 true
    • 对于企业部署设置为 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 类型的 Beta 支持。另请参阅 OTEL_AGENT_FEATURE_GATE_ARG 以启用 OTel 收集器中的 JSON 支持。
    • 指导:
    • 设置为 true 以在 ClickStack 中启用 JSON 支持。

OpenTelemetry 收集器

有关更多详细信息,请参见 "ClickStack OpenTelemetry Collector"

  • CLICKHOUSE_ENDPOINT

    • 默认值: 无(必需) 如果是独立镜像。如果是 All-in-one 或 Docker Compose 分发,则设置为集成的 ClickHouse 实例。
    • 描述: 要导出遥测数据的 ClickHouse 实例的 HTTPS URL。
    • 指导:
      • 必须是完整的 HTTPS 端点,包括端口(例如,https://clickhouse.example.com:8443
      • 收集器向 ClickHouse 发送数据时必需
  • CLICKHOUSE_USER

    • 默认值: default
    • 描述: 用于与 ClickHouse 实例进行身份验证的用户名。
    • 指导:
      • 确保该用户具有 INSERTCREATE TABLE 权限
      • 建议为提取创建专用用户
  • CLICKHOUSE_PASSWORD

    • 默认值: 无(如果启用身份验证,则必需)
    • 描述: 指定 ClickHouse 用户的密码。
    • 指导:
      • 如果用户帐户设置了密码,则为必需
      • 在生产部署中通过密钥安全存储
  • HYPERDX_LOG_LEVEL

    • 默认值: info
    • 描述: 收集器的日志详细程度级别。
    • 指导:
      • 接受类似 debuginfowarnerror 的值
      • 在故障排除期间使用 debug
  • OPAMP_SERVER_URL

    • 默认值: 无(必需) 如果是独立镜像。如果是 All-in-one 或 Docker Compose 分发,则指向部署的 HyperDX 实例。
    • 描述: 用于管理收集器的 OpAMP 服务器的 URL(例如,HyperDX 实例)。默认端口为 4320
    • 指导:
      • 必须指向您的 HyperDX 实例
      • 启用动态配置和安全提取
  • HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

    • 默认值: default
    • 描述: 收集器将遥测数据写入的 ClickHouse 数据库。
    • 指导:
      • 如果使用自定义数据库名称,则设置
      • 确保所指定的用户对该数据库有访问权限
  • OTEL_AGENT_FEATURE_GATE_ARG

    • 默认值: <空字符串>
    • 描述: 启用收集器中的功能标志。如果设置为 --feature-gates=clickhouse.json 则启用收集器中的 JSON 类型的 Beta 支持,确保创建具有该类型的架构。另请参见 BETA_CH_OTEL_JSON_SCHEMA_ENABLED 以在 HyperDX 中启用 JSON 支持。
    • 指导:
    • 设置为 true 以在 ClickStack 中启用 JSON 支持。

ClickHouse

ClickStack 附带的默认 ClickHouse 配置旨在用于多 TB 规模,但用户可以自由修改和优化以适应其工作负载。

要有效调整 ClickHouse,用户应了解关键存储概念,例如 partspartitionsshards and replicas,以及如何在插入时发生 merges。我们建议查看 primary indicessparse secondary indices 和数据跳过索引的基本知识,以及使用 TTL 生命周期管理数据生命周期的技术。

ClickStack 支持 schema customization - 用户可以修改列类型、提取新字段(例如,从日志中)、应用编解码器和字典,并使用投影加速查询。

此外,物化视图可以用于 transform or filter data during ingestion,前提是数据写入视图的源表,并且应用程序从目标表读取。

有关更多详细信息,请参阅 ClickHouse 文档中的架构设计、索引策略和数据管理最佳实践 - 大多数内容直接适用于 ClickStack 部署。