Theory
인프라
Loki 공식 문서 번역
setup
업그레이드
Overview

Loki 업그레이드

출처: https://grafana.com/docs/loki/latest/setup/upgrade/ (opens in a new tab)

Grafana Loki는 하위 호환성을 유지하기 위해 모든 노력을 기울여 업그레이드가 낮은 위험과 마찰을 갖도록 합니다.

안타깝게도 Loki는 소프트웨어이고 소프트웨어는 어렵기 때문에 때로는 사용 편의성과 유지보수 편의성 사이에서 결정을 내려야 할 때가 있습니다.

업그레이드에 어려움이 예상되는 경우 여기에 문서화할 것입니다.

더 많은 버전이 출시됨에 따라 여러 버전을 한 번에 이동할 때 예기치 않은 문제가 발생할 가능성이 높아집니다. 가능하다면 최신 상태를 유지하고 순차적으로 업데이트하십시오. 버전을 건너뛰고 싶다면 프로덕션을 업그레이드하기 전에 개발 환경에서 시도해 보십시오.

설정 변경 확인

Docker를 사용하여 다음과 같은 명령으로 Loki의 두 버전 간의 변경 사항을 확인할 수 있습니다:

export OLD_LOKI="2.9.4"
export NEW_LOKI="3.0.0"
export CONFIG_FILE=local-config.yaml
diff --color=always --side-by-side \
  <(docker run --rm -t -v "${PWD}":/config grafana/loki:"${OLD_LOKI}" -config.file=/etc/loki/"${CONFIG_FILE}" -print-config-stderr 2>&1 | sed '/Starting Loki/q' | tr -d '\r') \
  <(docker run --rm -t -v "${PWD}":/config grafana/loki:"${NEW_LOKI}" -config.file=/etc/loki/"${CONFIG_FILE}" -print-config-stderr 2>&1 | sed '/Starting Loki/q' | tr -d '\r') \
  | less -R

tr -d '\r'은 대부분의 사람들에게는 필요하지 않을 수 있지만, WSL2가 일부 윈도우 줄 바꿈 문자를 몰래 넣는 것 같습니다…

출력은 Loki를 실행하는 데 사용되는 전체 내부 구성 구조를 보여주므로 매우 장황합니다. 변경 사항만 표시하거나 다른 스타일의 출력을 선호하는 경우 diff 명령을 사용해 볼 수 있습니다.

Main / 미출시

3.4.0

Loki 3.4.0

새로운 객체 스토리지 클라이언트

Loki 릴리스 3.4.0은 Thanos 객체 스토리지 클라이언트 Go 모듈 (opens in a new tab)을 기반으로 하는 새로운 객체 스토리지 클라이언트를 도입합니다. 이는 선택적 기능입니다. 향후 릴리스에서는 이것이 스토리지를 구성하는 기본 방법이 되며 기존 스토리지 클라이언트는 더 이상 사용되지 않습니다.

새로운 스토리지 구성은 기존 형식과 다릅니다. 지원되는 스토리지 공급자 및 해당 구성 옵션의 전체 목록을 보려면 Thanos 스토리지 구성 참조를 참조하십시오.

이제 문서에는 Thanos 기반 스토리지 클라이언트를 사용하기 위한 마이그레이션 가이드 및 구성 예제도 포함되어 있습니다.

3.3.0

Loki 3.3.0

실험적 블룸 필터

Loki 3.3.0에서는 블룸 블록 형식이 변경되어 이전에 생성된 모든 블록이 새 형식과 호환되지 않습니다. 업그레이드하기 전에 객체 저장소의 모든 기존 블룸 블록을 삭제하는 것이 좋습니다. 블룸 블록과 메타는 구성된 객체 저장소의 bloom 경로 내에 저장합니다. 모든 블룸 블록을 제거하려면 객체 저장소의 bloom 경로 내에 있는 모든 객체를 삭제하십시오.

3.2.0

Loki 3.2.0

HTTP API

인스턴트 쿼리에 대한 API 엔드포인트 /api/v1/query는 이제 제공된 query 매개변수에 로그 선택기 쿼리가 포함된 경우 일관성 없는 결과를 반환하는 대신 HTTP 상태 400(잘못된 요청)을 반환합니다. 대신 범위 쿼리 엔드포인트 /api/v1/query_range(Grafana Explore의 Range 유형)를 사용하십시오.

구성

Loki는 -ruler.alertmanager-use-v2의 기본값을 false에서 true로 변경합니다. Alertmanager APIv1은 Alertmanager 0.16.0에서 더 이상 사용되지 않으며 0.27.0부터 제거되었습니다.

실험적 블룸 필터

참고: 실험적 기능은 급격한 변경 및/또는 제거의 대상이 될 수 있으며, 이는 부 버전 간에도 주요 변경 사항을 도입할 수 있습니다. 또한 일반 기능의 사용 중단 수명 주기를 따르지 않습니다.

쿼리 가속화를 위해 블룸 필터 블록을 빌드하는 블룸 압축기 구성 요소는 두 개의 새로운 구성 요소인 블룸 플래너와 블룸 빌더를 위해 제거되었습니다. 자세한 내용은 블룸을 사용한 쿼리 가속화 문서를 참조하십시오.

이 변경의 일부로 제거된 테넌트별 설정의 CLI 인수(및 해당 YAML 대응 항목):

  • -bloom-compactor.enable-compaction
  • -bloom-compactor.shard-size
  • -bloom-compactor.shard-size
  • -bloom-compactor.shard-size

이 변경의 일부로 다른 접두사로 이동된 테넌트별 설정의 CLI 인수:

  • -bloom-compactor.max-page-size가 -bloom-builder.max-page-size로 변경됨
  • -bloom-compactor.max-block-size가 -bloom-builder.max-block-size로 변경됨
  • -bloom-compactor.ngram-length가 -bloom-builder.ngram-length로 변경됨
  • -bloom-compactor.ngram-skip가 -bloom-builder.ngram-skip로 변경됨
  • -bloom-compactor.false-positive-rate가 -bloom-builder.false-positive-rate로 변경됨
  • -bloom-compactor.block-encoding가 -bloom-builder.block-encoding로 변경됨

limits_config 블록의 YAML 대응 항목은 동일하게 유지됩니다. -bloom-compactor. 접두사가 붙은 다른 모든 CLI 인수(및 해당 YAML 대응 항목)는 제거되었습니다.

3.0.0

참고: Loki 3.0으로 업그레이드하는 것에 대해 질문이 있는 경우 커뮤니티 Slack (opens in a new tab)의 #loki-3 채널에 참여하십시오. 또는 이 Github 문제 (opens in a new tab)에 의견을 남겨주십시오.

팁: 아직 TSDB로 마이그레이션하지 않은 경우 Loki 3.0으로 업그레이드하기 전에 마이그레이션하십시오.

Loki 3.0은 주요 버전 증가이며 몇 가지 주요 변경 사항이 있습니다. 대부분의 사람들이 마주칠 수 있다고 생각하는 것들의 간략한 목록은 다음과 같습니다:

기존 구성이 Loki 3.0에서 작동하는지 확인하려면:

  1. 컴퓨터의 빈 디렉터리에 구성을 loki-config.yaml이라는 파일에 복사합니다.
  2. 해당 디렉터리에서 이 명령을 실행합니다:
docker run --rm -t -v "${PWD}":/config grafana/loki:3.0.0 -config.file=/config/loki-config.yaml -verify-config=true

참고: 새로운 schema_config 항목을 도입하면 추가 유효성 검사 오류가 발생할 수 있습니다.

팁: common 구성 섹션에서 path_prefix를 구성하면 많은 구성을 절약하는 데 도움이 될 수 있습니다. 공통 구성 문서를 참조하십시오.

Helm 차트는 몇 가지 중요한 변경 사항을 거쳤으며 별도의 업그레이드 가이드가 있습니다: Helm 6.x로 업그레이드.

Loki 3.0.0

구조화된 메타데이터, Open Telemetry, 스키마 및 인덱스

Loki 3.0의 대표적인 기능은 Open Telemetry Protocol(OTLP)의 기본 지원입니다. 이는 Loki의 새로운 기능인 구조화된 메타데이터라는 레이블이나 로그 줄에 속하지 않는 메타데이터를 위한 장소 덕분에 가능해졌습니다. OTel 리소스 및 속성은 종종 인덱스나 로그 줄에 속하지 않는 데이터의 좋은 예입니다.

구조화된 메타데이터는 Loki 3.0에서 기본적으로 활성화되어 있지만 활성 스키마가 tsdb 인덱스 유형과 v13 스토리지 스키마를 모두 사용해야 합니다. 둘 다 사용하지 않는 경우 두 가지 옵션이 있습니다:

  • 3.0으로 업데이트하기 전에 인덱스 버전과 스키마 버전을 업그레이드하십시오. 스키마 구성 업그레이드를 참조하십시오.
  • 구조화된 메타데이터(및 따라서 OTLP 지원)를 비활성화하고 3.0으로 업그레이드한 후 스키마 마이그레이션을 수행하십시오. 이는 limits_config 섹션에서 "allow_structured_metadata": false를 설정하거나 명령줄 인수 -validation.allow-structured-metadata=false를 설정하여 수행할 수 있습니다.

service_name 레이블

Loki 3.0은 기본적으로 수집된 모든 로그에 service_name 레이블을 자동으로 할당합니다. 서비스 이름은 Open Telemetry 의미 체계 규칙에 필요한 것이며 Grafana Labs가 향후 사용자 인터페이스 및 쿼리 경험에 구축하고 있는 것입니다.

Loki는 다음 레이블을 이 순서대로 찾아 service_name 레이블을 만들려고 시도합니다.

  • service_name
  • service
  • app
  • application
  • name
  • app_kubernetes_io_name
  • container
  • container_name
  • component
  • workload
  • job

목록과 일치하는 레이블이 없으면 unknown_service 값이 적용됩니다. limits_config 블록에서 discover_service_name에 레이블 목록을 제공하여 이 목록을 변경할 수 있습니다.

참고: 이미 service_label을 사용하고 있는 경우 Loki는 새로운 할당을 하지 않습니다.

discover_service_name에 빈 값을 제공하여 이를 비활성화할 수 있습니다.

shipper 구성에서 shared_store 및 shared_store_key_prefix 제거

TSDB 및 BoltDB shipper에 대한 공유 저장소를 구성하기 위한 다음 CLI 플래그 및 해당 YAML 설정이 이제 제거되었습니다.

  • -boltdb.shipper.shared-store
  • -tsdb.shipper.shared-store

앞으로는 period_config의 object_store 설정이 인덱스에 대한 저장소를 구성하는 데 사용됩니다. 이는 청크와 인덱스 파일이 주어진 기간 동안 동일한 스토리지 버킷에 함께 있도록 강제합니다. 우리는 스토리지 구성을 단순화하고 잘못된 구성 가능성을 줄이기 위해 공유 저장소 설정을 제거하고 있습니다.

경고: 이 변경으로 Loki는 더 이상 주어진 기간 동안 청크와 인덱스를 다른 스토리지 버킷에 저장하는 것을 허용하지 않습니다. 이는 -boltdb.shipper.shared-store 또는 -tsdb.shipper.shared-store를 period_config의 object_store와 다른 값으로 설정하여 청크와 인덱스를 다른 스토리지 버킷에 저장하는 설정에 대한 주요 변경 사항입니다.

  • 이전에 -boltdb.shipper.shared-store, -tsdb.shipper.shared-store 또는 해당 YAML 설정을 구성하지 않은 경우 업그레이드의 일부로 변경이 필요하지 않습니다.
  • -boltdb.shipper.shared-store 또는 해당 YAML 설정을 구성한 경우:
    • boltdb-shipper를 인덱스로 사용하는 모든 기간에 대해 object_store 값과 일치하는 경우 삭제된 구성 옵션 사용을 제거하는 것 외에 추가 변경이 필요하지 않습니다.
    • 불일치가 있는 경우 -boltdb.shipper.shared-store가 object_store와 일치하지 않는 기간에 대한 인덱스에 대한 액세스 권한을 잃게 됩니다.
      • 이러한 인덱스를 쿼리할 수 있도록 하려면 인덱스 테이블을 object_store에 구성된 저장소로 이동하거나 복사해야 합니다.
  • -tsdb.shipper.shared-store 또는 해당 YAML 설정을 구성한 경우:
    • tsdb를 인덱스 유형으로 사용하는 모든 기간에 대해 object_store 값과 일치하는 경우 삭제된 구성 옵션 사용을 제거하는 것 외에 추가 변경이 필요하지 않습니다.
    • 불일치가 있는 경우 -tsdb.shipper.shared-store가 object_store와 일치하지 않는 기간에 대한 인덱스에 대한 액세스 권한을 잃게 됩니다.
      • 이러한 인덱스를 쿼리할 수 있도록 하려면 인덱스 테이블을 object_store에 구성된 저장소로 이동하거나 복사해야 합니다.

TSDB 및 BoltDB shipper에 대한 경로 접두사를 구성하기 위한 다음 CLI 플래그 및 해당 YAML 설정이 이제 제거되었습니다.

  • -boltdb.shipper.shared-store.key-prefix
  • -tsdb.shipper.shared-store.key-prefix

인덱스 저장을 위한 경로 접두사는 이제 period_config의 index 키 아래에 path_prefix를 설정하여 구성할 수 있습니다. 이를 통해 사용자는 새 기간 구성을 추가하여 경로 접두사를 변경할 수 있습니다.

period_config:
  index:
    path_prefix: "index/"
  period: 24h

참고: path_prefix는 TSDB 및 BoltDB 인덱스에만 적용됩니다. 이 설정은 레거시 인덱스에 영향을 미치지 않습니다.

path_prefix는 제거된 구성의 기본값과 동일한 index/로 기본 설정됩니다.

  • 이전에 -boltdb.shipper.shared-store.key-prefix, -tsdb.shipper.shared-store.key-prefix 또는 해당 YAML 설정을 구성하지 않은 경우 변경이 필요하지 않습니다.
  • -boltdb.shipper.shared-store.key-prefix 또는 해당 YAML 설정을 index/ 이외의 값으로 구성한 경우 boltdb-shipper를 인덱스로 사용하는 모든 기존 기간 구성에 path_prefix가 이전에 구성된 값으로 설정되어 있는지 확인하십시오.
  • -tsdb.shipper.shared-store.key-prefix 또는 해당 YAML 설정을 index/ 이외의 값으로 구성한 경우 tsdb를 인덱스로 사용하는 모든 기존 기간 구성에 path_prefix가 이전에 구성된 값으로 설정되어 있는지 확인하십시오.

compactor 구성에서 shared_store 및 shared_store_key_prefix 제거

compactor에 대한 공유 저장소 및 경로 접두사를 구성하기 위한 다음 CLI 플래그 및 해당 YAML 설정이 이제 제거되었습니다.

  • -boltdb.shipper.compactor.shared-store
  • -boltdb.shipper.compactor.shared-store.key-prefix

앞으로 compactor는 인덱스 유형이 tsdb 또는 boltdb-shipper인 period configs에 구성된 모든 객체 저장소에서 압축 및 보존을 실행합니다.

delete_request_store는 명시적으로 구성해야 합니다

보존이 활성화된 경우 -compactor.delete-request-store 또는 해당 YAML 설정을 명시적으로 구성해야 합니다. 이는 삭제 요청을 저장하는 데 필요합니다. 삭제 요청이 저장되는 경로 접두사는 -compactor.delete-request-store.key-prefix에 의해 결정되며 기본값은 index/입니다.

async_cache_write_back_concurrency 및 async_cache_write_back_buffer_size 구성이 제거되었습니다

이러한 구성은 cache-config의 Background 구성과 중복되었습니다. async_cache_write_back_concurrency는 writeback_goroutines로 설정할 수 있습니다. async_cache_write_back_buffer_size는 writeback_buffer로 설정할 수 있습니다. 또한 Background 구성에서는 writeback_size_limit을 설정하여 쓰기 저장 객체에 대한 객체 수 대신 최대 메모리 양을 설정할 수 있습니다.

레거시 ingester 종료 핸들러가 제거되었습니다

이미 사용되지 않는 핸들러 /ingester/flush_shutdown은 /ingester/shutdown?flush=true를 위해 제거되었습니다.

Ingester 구성 max_transfer_retries가 제거되었습니다

max_transfer_retries(-ingester.max-transfer-retries) 설정은 Write Ahead log(WAL)를 위해 제거되었습니다. 롤링 재시작 중에 이전 ingester가 종료될 때 새 ingester로 청크를 전송할 수 있도록 하는 데 사용되었습니다. 이 설정에 대한 대안은 다음과 같습니다. A. (권장) WAL을 활성화하고 새 ingester가 WAL을 재생하도록 의존합니다.

  • 선택적으로 flush_on_shutdown(-ingester.flush-on-shutdown)을 활성화하여 종료 시 장기 저장소로 플러시할 수 있습니다. B. ingester /shutdown?flush=true 엔드포인트를 통해 종료 중에 수동으로 플러시합니다.

런타임 재정의 구성 파일의 default 섹션이 제거되었습니다

이는 2.9에서 도입되었으며 널리 사용되지는 않았을 것입니다. 이는 런타임 구성 파일로 Loki를 실행하고 2.9에 추가된 새 default 블록을 채운 경우에만 영향을 미칩니다. default 블록은 제거되었고 대신 표준 Loki 구성에 operational_config라는 최상위 구성이 있습니다. 여기에서 런타임 구성에 대한 기본값을 설정할 수 있습니다.

use_boltdb_shipper_as_backup 구성이 제거되었습니다

use_boltdb_shipper_as_backup(-tsdb.shipper.use-boltdb-shipper-as-backup) 설정은 TSDB 스토리지 개발의 잔재였습니다. TSDB가 여전히 매우 실험적일 때 TSDB와 BoltDB 모두에 쓰기를 허용하는 데 사용되었습니다. TSDB가 이제 안정적이고 권장되는 인덱스 유형이므로 이 설정은 관련이 없어져 제거되었습니다. 이전 기본값 false가 적용됩니다.

더 이상 사용되지 않는 구성 옵션이 제거되었습니다

  • 이미 사용되지 않는 store.max-look-back-period CLI 플래그 및 해당 YAML 설정이 제거되었습니다. 대신 querier.max-query-lookback 구성을 사용하십시오.
  • 이미 사용되지 않는 -querier.engine.timeout CLI 플래그 및 해당 YAML 설정이 제거됩니다.
  • 또한 querier YAML 섹션에서 query_timeout을 제거합니다. querier 아래에 query_timeout을 구성하는 대신 이제 Limits Config에서 구성합니다.
  • s3.sse-encryption이 제거되었습니다. AWS는 이제 모든 버킷의 암호화를 SSE-S3로 기본 설정합니다. SSE 유형을 설정하려면 sse.type을 사용하십시오.
  • ruler.wal-cleaer.period가 제거되었습니다. 대신 ruler.wal-cleaner.period를 사용하십시오.
  • experimental.ruler.enable-api가 제거되었습니다. 대신 ruler.enable-api를 사용하십시오.
  • split_queries_by_interval이 query_range YAML 섹션에서 제거되었습니다. 대신 Limits Config에서 구성할 수 있습니다.
  • frontend.forward-headers-list CLI 플래그 및 해당 YAML 설정이 제거되었습니다.
  • frontend.cache-split-interval CLI 플래그가 제거되었습니다. 결과 캐싱 간격은 이제 querier.split-queries-by-interval에 의해 결정됩니다.
  • querier.worker-parallelism CLI 플래그 및 해당 yaml 설정은 이미 존재하는 querier.max-concurrent에 추가적인 가치를 제공하지 않으므로 이제 제거되었습니다. querier.max-concurrent를 구성하여 쿼리어가 처리하는 최대 동시 요청 수를 제한하는 것이 좋습니다.
  • ruler.evaluation-delay-duration CLI 플래그 및 해당 YAML 설정이 제거되었습니다.
  • validation.enforce-metric-name CLI 플래그 및 해당 YAML 설정이 제거되었습니다.
  • boltdb.shipper.compactor.deletion-mode CLI 플래그 및 해당 YAML 설정이 제거되었습니다. 대신 compactor.deletion-mode CLI 플래그 또는 Limits Config의 deletion_mode YAML 설정을 구성할 수 있습니다.
  • boltdb.shipper.compactor. 접두사를 사용하는 Compactor CLI 플래그가 제거되었습니다. 대신 compactor. 접두사가 있는 CLI 플래그를 사용할 수 있습니다.

Distributor 메트릭 변경

loki_distributor_ingester_append_failures_total 메트릭은 loki_distributor_ingester_append_timeouts_total을 위해 제거되었습니다. 이 새로운 메트릭은 ingester에 문제가 있다는 더 명확한 신호를 제공하며 이 메트릭은 높은 신호 알림에 사용할 수 있습니다.

Thanos 스토리지 클라이언트로 마이그레이션JVM