.env 파일로 설정을 변경할 수 있습니다.
또는 docker-compose.yaml 파일에서 설정을 직접 덮어쓸 수 있습니다. 예를 들면 다음과 같습니다.
예시:
--set 플래그를 사용해 설정을 맞춤 설정할 수 있습니다.
values.yaml을 수정하세요. 기본값을 확인하려면 다음을 실행하십시오:
LogsTracesMetricsSessions
Team Settings -> Sources에서 수행할 수 있으며, 아래는 로그에 대한 예시입니다:

ClickStack과 함께 제공되는 ClickHouse의 기본 스키마는 OTel collector용 ClickHouse exporter가 생성하는 스키마입니다. 이러한 컬럼 이름은 여기에 문서화된 OTel 공식 사양과 연관됩니다.
Materialized view를 Log 및 Trace 데이터 소스에 등록하면, 조건에 맞는 집계 쿼리는 원본 테이블이 아닌 사전 집계된 뷰에서 결과를 가져옵니다. 뷰 생성 및 등록 방법은 “Materialized views”를 참조하십시오.
등록된 각 뷰에는 다음 설정을 지정합니다.
이러한 설정 대부분은 대상 테이블을 선택하면 뷰의 스키마에서 자동으로 추론됩니다.
메타데이터 materialized view는 필터 및 자동 완성을 위한 필드 디스커버리를 가속합니다. Log 및 Trace 데이터 소스에 구성할 수 있습니다.
강조 속성과 강조 트레이스 속성은 Log 및 Trace 데이터 소스에서 구성할 수 있습니다.
- 강조 속성은 로그 또는 스팬 세부 정보를 볼 때 각 로그 또는 스팬에 표시되는 컬럼 또는 표현식입니다.
- 강조 트레이스 속성은 트레이스 내 각 로그 또는 스팬에서 조회되어 트레이스 워터폴 위에 표시되는 컬럼 또는 표현식입니다.
예를 들어, 이 trace 소스는 강조 속성과 강조 트레이스 속성으로 구성되어 있습니다.



Logs: 트레이스 및 메트릭과 연관시킬 수 있습니다.Traces: 로그, 세션 및 메트릭과 연관시킬 수 있습니다.Metrics: 로그와 연관시킬 수 있습니다.Sessions: 트레이스와 연관시킬 수 있습니다.

ClickHouse Cloud의 HyperDXHyperDX가 ClickHouse Cloud에서 관리되는 경우 이러한 설정은 수정할 수 없습니다.
-
HYPERDX_API_KEY- 기본값: None (필수)
- 설명: HyperDX API의 인증 키입니다.
- 지침:
- telemetry 및 로깅에 필요합니다
- 로컬 개발 환경에서는 비어 있지 않은 값이라면 아무 값이나 사용할 수 있습니다
- 운영 환경에서는 안전하고 고유한 키를 사용하십시오
- 계정 생성 후 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로 유지합니다 - 엔터프라이즈 배포에서는
false로 설정합니다 - 사용 가능한 기능에 영향을 줍니다
- 기본값:
-
IS_LOCAL_MODE- 기본값:
false - 설명: 로컬 모드로 실행할지 여부를 나타냅니다.
- 지침:
- 로컬 개발 환경에서는
true로 설정하세요 - 일부 운영 기능을 비활성화합니다
- 테스트 및 개발에 유용합니다
- 기본값:
-
EXPRESS_SESSION_SECRET- 기본값:
hyperdx is cool 👋 - 설명: Express session 관리를 위한 시크릿입니다.
- 지침:
- 프로덕션 환경에서는 변경하세요
- 충분히 강력한 무작위 문자열을 사용하세요
- 외부에 노출되지 않도록 안전하게 관리하세요
- 기본값:
-
ENABLE_SWAGGER- 기본값:
false - 설명: Swagger API 문서의 활성화 여부를 전환합니다.
- 지침:
- API 문서를 활성화하려면
true로 설정하세요 - 개발 및 테스트에 유용합니다
- production 환경에서는 비활성화하십시오
- 기본값:
-
BETA_CH_OTEL_JSON_SCHEMA_ENABLED- 기본값:
false - 설명: HyperDX에서 JSON 타입에 대한 베타 지원을 활성화합니다. OTel collector에서 JSON 지원을 활성화하려면
OTEL_AGENT_FEATURE_GATE_ARG도 참조하십시오. - 지침:
- 베타 기능을 활성화합니다. JSON 타입 스키마는 일반적인 관측성 워크로드에는 권장되지 않습니다. 두 방식의 비교와 각각이 적합한 사용 사례는 Map vs JSON type를 참조하십시오.
- ClickStack UI에서 JSON 지원을 활성화하려면
true로 설정하십시오.
- 기본값:
-
CLICKHOUSE_ENDPOINT- Default: 독립 실행형 이미지인 경우 *None (필수)*입니다. All-in-one 또는 Docker Compose 배포판에서는 통합된 ClickHouse 인스턴스로 설정됩니다.
- Description: 텔레메트리 데이터를 내보낼 대상 ClickHouse 인스턴스의 HTTPS URL입니다.
- Guidance:
- 포트를 포함한 전체 HTTPS 엔드포인트여야 합니다(예:
https://clickhouse.example.com:8443) - collector가 데이터를 ClickHouse로 전송하려면 필수입니다
- 포트를 포함한 전체 HTTPS 엔드포인트여야 합니다(예:
-
CLICKHOUSE_USER- Default:
default - Description: ClickHouse 인스턴스에 인증할 때 사용하는 사용자 이름입니다.
- Guidance:
- 해당 사용자에게
INSERT및CREATE TABLE권한이 있는지 확인하십시오 - 수집 전용 사용자를 별도로 생성하는 것이 좋습니다
- 해당 사용자에게
- Default:
-
CLICKHOUSE_PASSWORD- Default: None (인증이 활성화된 경우 필수)
- Description: 지정된 ClickHouse 사용자의 비밀번호입니다.
- Guidance:
- 사용자 계정에 비밀번호가 설정되어 있으면 필수입니다
- 운영 배포에서는 시크릿을 사용해 안전하게 저장하십시오
-
HYPERDX_LOG_LEVEL- Default:
info - Description: collector의 로그 상세도 수준입니다.
- Guidance:
debug,info,warn,error등의 값을 사용할 수 있습니다- 문제 해결 중에는
debug를 사용하십시오
- Default:
-
OPAMP_SERVER_URL- Default: 독립 실행형 이미지인 경우 *None (필수)*입니다. All-in-one 또는 Docker Compose 배포판에서는 배포된 HyperDX 인스턴스를 가리킵니다.
- Description: collector를 관리하는 데 사용하는 OpAMP 서버의 URL입니다(예: HyperDX 인스턴스). 기본 포트는
4320입니다. - Guidance:
- HyperDX 인스턴스를 가리켜야 합니다
- 동적 구성과 안전한 수집을 활성화합니다
- 생략하면
OTLP_AUTH_TOKEN값이 지정된 경우를 제외하고 안전한 수집이 비활성화됩니다.
-
OTLP_AUTH_TOKEN- Default: None. 독립 실행형 이미지에서만 사용됩니다.
- Description: OTLP 인증 토큰을 지정할 수 있습니다. 설정하면 모든 통신에 이 Bearer token이 필요합니다.
- Guidance:
- 운영 환경에서 독립 실행형 collector 이미지를 사용하는 경우 권장됩니다.
-
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE- Default:
default - Description: collector가 텔레메트리 데이터를 기록하는 ClickHouse 데이터베이스입니다.
- Guidance:
- 사용자 지정 데이터베이스 이름을 사용하는 경우 설정하십시오
- 지정된 사용자가 이 데이터베이스에 접근할 수 있는지 확인하십시오
- Default:
-
OTEL_AGENT_FEATURE_GATE_ARG- Default:
<empty string> - Description: collector에서 기능 플래그를 활성화합니다.
--feature-gates=clickhouse.json으로 설정하면 collector에서 JSON 타입에 대한 베타 지원이 활성화되어 스키마가 해당 타입으로 생성됩니다. HyperDX에서 JSON 지원을 활성화하려면BETA_CH_OTEL_JSON_SCHEMA_ENABLED도 참조하십시오. - Guidance:
- 베타 기능을 활성화합니다. JSON 타입 스키마는 일반적인 관측성 워크로드에는 권장되지 않습니다. 비교와 각 방식이 적합한 경우는 Map vs JSON type을 참조하십시오.
- 새 테이블을 JSON 타입으로 생성하려면
--feature-gates=clickhouse.json으로 설정하십시오.
- Default: