Logs

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

로그

OpenSearch 로그에는 클러스터 운영을 모니터링하고 문제를 트러블슈팅하는 데 유용한 정보가 담겨 있어요. 로그의 위치는 설치 방식에 따라 달라져요:

Docker에서는 OpenSearch가 대부분의 로그를 콘솔에 기록하고 나머지는 opensearch/logs/에 저장해요. tarball 설치 방식도 opensearch/logs/를 사용해요.
대부분의 Linux 설치에서는 OpenSearch가 로그를 /var/log/opensearch/에 기록해요.

로그는 .log(일반 텍스트)와 .json 파일로 제공돼요. OpenSearch 로그의 권한은 기본적으로 -rw-r--r--라서 노드의 모든 사용자 계정이 로그를 읽을 수 있어요. 이 동작은 log4j2.properties에서 filePermissions 옵션을 사용해 로그 타입별로 변경할 수 있어요. 예를 들어 JSON 서버 로그의 권한을 바꾸려면 appender.rolling.filePermissions = rw-r-----을 추가하면 돼요. 자세한 내용은 Log4j 2 문서를 참고하세요.

애플리케이션 로그

애플리케이션 로그에는 OpenSearch가 Apache Log4j 2와 그 내장 로그 레벨(심각도가 낮은 것부터 높은 것 순서)을 사용해요. 다음 표는 로깅 설정을 설명해요.

설정	데이터 타입	설명
`logger.org.opensearch.discovery`	String	로거는 Log4j2의 내장 로그 레벨인 `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`를 받아들여요. 기본값은 `INFO`예요.

기본 로그 레벨(logger.level)을 바꾸는 대신, 개별 OpenSearch 모듈의 로그 레벨을 변경해요:

PUT /_cluster/settings
{
  "persistent" : {
    "logger.org.opensearch.index.reindex" : "DEBUG",
    "logger.org.opensearch.indices.recovery": "TRACE"
  }
}

{% include copy-curl.html %}

일반적인 카테고리는 공통 코어 로깅 카테고리와 플러그인 로거 카테고리에서 찾을 수 있어요. 하지만 모듈을 식별하는 가장 쉬운 방법은 경로가 축약되는 로그(예: o.o.i.r)가 아니라 OpenSearch 소스 코드를 확인하는 거예요. {: .tip }

이 샘플 변경을 적용하고 나면 reindex 작업 중에 OpenSearch가 훨씬 더 상세한 로그를 출력해요:

[2019-10-18T16:52:51,184][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: starting
[2019-10-18T16:52:51,186][DEBUG][o.o.i.r.TransportReindexAction] [node1] executing initial scroll against [some-index]
[2019-10-18T16:52:51,291][DEBUG][o.o.i.r.TransportReindexAction] [node1] scroll returned [3] documents with a scroll id of [DXF1Z==]
[2019-10-18T16:52:51,292][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: got scroll response with [3] hits
[2019-10-18T16:52:51,294][DEBUG][o.o.i.r.WorkerBulkByScrollTaskState] [node1] [1626]: preparing bulk request for [0s]
[2019-10-18T16:52:51,297][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: preparing bulk request
[2019-10-18T16:52:51,299][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: sending [3] entry, [222b] bulk request
[2019-10-18T16:52:51,310][INFO ][o.e.c.m.MetaDataMappingService] [node1] [some-new-index/R-j3adc6QTmEAEb-eAie9g] create_mapping [_doc]
[2019-10-18T16:52:51,383][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: got scroll response with [0] hits
[2019-10-18T16:52:51,384][DEBUG][o.o.i.r.WorkerBulkByScrollTaskState] [node1] [1626]: preparing bulk request for [0s]
[2019-10-18T16:52:51,385][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: preparing bulk request
[2019-10-18T16:52:51,386][DEBUG][o.o.i.r.TransportReindexAction] [node1] [1626]: finishing without any catastrophic failures
[2019-10-18T16:52:51,395][DEBUG][o.o.i.r.TransportReindexAction] [node1] Freed [1] contexts

DEBUG와 TRACE 레벨은 엄청나게 장황해요. 문제를 트러블슈팅하려고 둘 중 하나를 활성화했다면, 작업을 마친 후에는 비활성화하세요.

로그 레벨을 변경하는 다른 방법도 있어요:

opensearch.yml에 다음 줄을 추가해요:
```
logger.org.opensearch.index.reindex: debug
```
{% include copy.html %}

여러 클러스터에 걸쳐 로깅 설정을 재사용하거나 단일 노드의 시작 문제를 디버깅하려면 opensearch.yml을 수정하는 방법이 가장 적합해요.
log4j2.properties를 수정해요:
```
# Define a new logger with unique ID of reindex
logger.reindex.name = org.opensearch.index.reindex
# Set the log level for that ID
logger.reindex.level = debug
```
{% include copy.html %}

이 방식은 매우 유연하지만 Log4j 2 프로퍼티 파일 문법에 익숙해야 해요. 일반적으로는 다른 옵션들이 더 간단한 설정 경험을 제공해요.

설정 디렉터리의 기본 log4j2.properties 파일을 살펴보면 OpenSearch 전용 변수가 몇 가지 보여요:
```
appender.console.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] [%node_name]%marker %m%n
appender.rolling_old.fileName = ${sys:opensearch.logs.base_path}${sys:file.separator}${sys:opensearch.logs.cluster_name}.log
```
- ${sys:opensearch.logs.base_path}는 로그가 저장되는 디렉터리예요(예: /var/log/opensearch/).
- ${sys:opensearch.logs.cluster_name}은 클러스터의 이름이에요.
- ${sys:opensearch.logs.node_name}은 노드의 이름이에요.
- [%node_name]은 노드의 이름이에요.

공통 코어 로깅 카테고리

다음 표는 공통 코어 로깅 카테고리를 정리한 거예요.

로거 키 접두사	설명
`org.opensearch.action`	`index`, `bulk`, `get`, `cluster` 액션 같은 트랜스포트 액션이에요. 노드 간 요청 실행을 추적할 때 유용해요.
`org.opensearch.cluster`	클러스터 상태 발행, 라우팅, 메타데이터 업데이트예요. 클러스터 형성, 라우팅, 할당 문제에 활성화하세요.
`org.opensearch.discovery`	노드 디스커버리와 클러스터 코디네이션이에요. 클러스터 형성이나 네트워크 파티션 테스트 중에 도움이 돼요. 하위 패키지에는 클라우드 디스커버리가 포함돼요.
`org.opensearch.gateway`	게이트웨이, ClusterState, 복구와 할당이에요. 노드 재시작, 샤드 할당, 디스크 및 원격 스토리지에서의 샤드 복구에 유용해요.
`org.opensearch.http`	저수준 HTTP 레이어의 요청 처리예요. HTTP 통신과 설정 관련 문제에 사용하세요.
`org.opensearch.index`	엔진, translog, 샤드 작업 같은 인덱스별 내부 동작이에요. 샤드/엔진 동작 디버깅에 사용하세요.
`org.opensearch.indices`	복구, 스토리지, 클러스터 상태 서비스 같은 인덱스 간 서비스예요. 샤드 복구와 인덱싱 압박 분석 중에 활성화하세요.
`org.opensearch.ingest`	Ingest 파이프라인과 프로세서예요. 파이프라인 실행을 디버깅할 때 활성화하세요.
`org.opensearch.node`	노드 라이프사이클과 부트스트랩이에요. 부팅 문제를 해결할 때 유용해요.
`org.opensearch.repositories`	Amazon Simple Storage Service(Amazon S3), Amazon Elastic File System(Amazon EFS) 등과의 스냅샷/복원 리포지토리 상호작용이에요. 리포지토리 오류와 스냅샷 조정에 사용하세요.
`org.opensearch.rest`	REST 핸들러와 액션 라우팅이에요. REST API 처리 세부 사항에 도움이 돼요.
`org.opensearch.script`	스크립팅 엔진이에요. 스크립트 컴파일과 실행 디버깅에 사용하세요.
`org.opensearch.search`	`query`, `fetch`, `rewrite` 같은 검색 페이즈예요. 쿼리 실행 디버깅에 활성화하세요.
`org.opensearch.snapshots`	스냅샷과 복원 오케스트레이션이에요. 스냅샷 라이프사이클을 진단할 때 사용하세요.
`org.opensearch.threadpool`	스레드 풀 실행이에요. 큐잉과 풀 포화 상태를 이해하는 데 도움이 돼요.
`org.opensearch.transport`	노드 간 트랜스포트 TCP 레이어예요. 노드 간 통신 문제에 사용하세요.
`org.opensearch.deprecation`	지원 중단 경고예요. 업그레이드 시 지원 중단된 API와 설정을 찾는 데 유용해요.

플러그인 로거 카테고리

다음 표는 일반적인 플러그인 로거 카테고리를 정리한 거예요.

플러그인	로거 접두사 예시	설명
Security	`org.opensearch.security`	Security 플러그인 내의 인증, 권한 부여, TLS를 디버깅하는 데 사용해요.
k-NN	`org.opensearch.knn`	k-NN 인덱스 빌드, 검색, 메모리 관리를 디버깅하는 데 사용해요.
ML Commons	`org.opensearch.ml`	모델 등록, 추론, 태스크 러너에 사용해요.
Alerting	`org.opensearch.alerting`	실행과 알림을 모니터링하는 데 사용해요.
Index Management	`org.opensearch.indexmanagement`	Index State Management(ISM) 정책, 롤업, 트랜스폼에 사용해요.
Discovery -- Amazon Elastic Compute Cloud(Amazon EC2)	`org.opensearch.discovery.ec2`	클라우드 디스커버리 정보예요.

에러 로그

OpenSearch는 WARN, ERROR, FATAL 레벨에서 에러를 기록해요. 또한 DEBUG 레벨의 특정 예외들도 기록하는데, 여기에는 다음이 포함돼요:

org.opensearch.index.mapper.MapperParsingException
org.opensearch.index.query.QueryShardException
org.opensearch.action.search.SearchPhaseExecutionException
org.opensearch.common.util.concurrent.OpenSearchRejectedExecutionException
java.lang.IllegalArgumentException

에러 로그는 다음을 포함한 다양한 상황에서 트러블슈팅에 도움이 돼요:

Painless 스크립트 컴파일 문제
잘못된 쿼리
인덱싱 문제
스냅샷 실패
Index State Management 마이그레이션 실패

매퍼 파싱 예외 범위

매퍼 파싱 예외는 Put Mapping API 요청처럼 명시적인 매핑 요청으로 발생했을 때만 기록돼요. Bulk API나 Index API 요청처럼 문서 인덱싱 작업으로 발생했을 때는 기록되지 않아요. 예를 들어 문서에 인덱스 매핑과 충돌하는 필드 값이 들어 있으면(예: integer 필드에 string 값을 보낼 때) Bulk API는 응답 본문에 mapper_parsing_exception을 반환하지만, 이 에러는 에러 로그에 기록되지 않아요. 벌크 인덱싱 중에 mapper_parsing_exception을 유발하는 문서를 찾으려면 에러 로그에 의존하기보다 Bulk API 응답의 에러를 확인하세요.

검색 요청 슬로우 로그

버전 2.12에 새로 추가된 기능으로, OpenSearch는 검색을 위한 요청 수준 슬로우 로그를 제공해요. 이 로그는 임계값을 기준으로 무엇이 "느린" 요청인지 판단해요. 임계값을 초과하는 모든 요청이 기록돼요.

검색 요청 슬로우 로그는 Cluster Settings API를 통해 동적으로 활성화해요. 샤드 슬로우 로그와 달리, 검색 요청 슬로우 로그의 임계값은 요청 전체 소요 시간을 기준으로 설정돼요. 기본적으로 로그는 비활성화되어 있어요(모든 임계값이 -1로 설정됨).

PUT /_cluster/settings
{
"persistent" : {
      "cluster.search.request.slowlog.level" : "TRACE",
      "cluster.search.request.slowlog.threshold.warn": "10s",
      "cluster.search.request.slowlog.threshold.info": "5s",
      "cluster.search.request.slowlog.threshold.debug": "2s",
      "cluster.search.request.slowlog.threshold.trace": "10ms"
}
}

{% include copy-curl.html %}

opensearch_index_search_slowlog.log의 한 줄은 다음과 같을 수 있어요:

[2023-10-30T15:47:42,630][TRACE][c.s.r.slowlog] [runTask-0] took[80.8ms], took_millis[80], phase_took_millis[{expand=0, query=39, fetch=22}], total_hits[4 hits], search_type[QUERY_THEN_FETCH], shards[{total: 10, successful: 10, skipped: 0, failed: 0}], indices[index_1, index_2, my_index_*], source[{"query":{"match_all":{"boost":1.0}}}], id[]

검색 요청 슬로우 로그는 임계값을 낮게 설정하면 상당한 디스크 공간을 소모하고 성능에도 영향을 줄 수 있어요. 트러블슈팅이나 성능 튜닝을 위해서는 일시적으로만 활성화하는 걸 고려하세요. 검색 요청 슬로우 로그를 비활성화하려면 모든 임계값을 -1로 되돌리면 돼요. {: .important}

샤드 슬로우 로그

OpenSearch에는 성능 문제를 파악하는 데 도움이 되는 두 가지 샤드 슬로우 로그가 있어요. 바로 검색 슬로우 로그와 인덱싱 슬로우 로그예요.

이 로그들도 임계값을 기준으로 "느린" 검색이나 "느린" 인덱싱 작업을 판단해요. 예를 들어 쿼리가 완료되는 데 15초 넘게 걸리면 느리다고 판단할 수 있죠. 모듈별로 설정하는 애플리케이션 로그와 달리, 슬로우 로그는 인덱스별로 설정해요. 기본적으로 두 로그 모두 비활성화되어 있어요(모든 임계값이 -1로 설정됨).

검색 요청 슬로우 로그와 달리, 샤드 슬로우 로그의 임계값은 개별 샤드의 소요 시간을 기준으로 설정돼요.

GET {some-index}/_settings?include_defaults=true
{
  "indexing": {
    "slowlog": {
      "reformat": "true",
      "threshold": {
        "index": {
          "warn": "-1",
          "trace": "-1",
          "debug": "-1",
          "info": "-1"
        }
      },
      "source": "1000",
      "level": "TRACE"
    }
  },
  "search": {
    "slowlog": {
      "level": "TRACE",
      "threshold": {
        "fetch": {
          "warn": "-1",
          "trace": "-1",
          "debug": "-1",
          "info": "-1"
        },
        "query": {
          "warn": "-1",
          "trace": "-1",
          "debug": "-1",
          "info": "-1"
        }
      }
    }
  }
}

{% include copy-curl.html %}

이 로그들을 활성화하려면 임계값 중 하나 이상을 올리면 돼요:

PUT {some-index}/_settings
{
  "indexing": {
    "slowlog": {
      "threshold": {
        "index": {
          "warn": "15s",
          "trace": "750ms",
          "debug": "3s",
          "info": "10s"
        }
      },
      "source": "500",
      "level": "INFO"
    }
  }
}

{% include copy-curl.html %}

이 예시에서 OpenSearch는 15초 이상 걸리는 인덱싱 작업은 WARN 레벨로, 10~14.x초 걸리는 작업은 INFO 레벨로 기록해요. 임계값을 0초로 설정하면 모든 작업이 기록되는데, 슬로우 로그가 실제로 활성화됐는지 테스트할 때 유용해요.

reformat은 문서의 _source 필드를 한 줄로 기록할지(true) 여러 줄에 걸치게 할지(false)를 지정해요.
source는 기록할 문서 _source 필드의 문자 수예요.
level은 포함할 최소 로그 레벨이에요.

opensearch_index_indexing_slowlog.log의 한 줄은 다음과 같을 수 있어요:

node1 | [2019-10-24T19:48:51,012][WARN][i.i.s.index] [node1] [some-index/i86iF5kyTyy-PS8zrdDeAA] took[3.4ms], took_millis[3], type[_doc], id[1], routing[], source[{"title":"Your Name", "Director":"Makoto Shinkai"}]

샤드 슬로우 로그는 임계값을 낮게 설정하면 상당한 디스크 공간을 소모하고 성능에도 영향을 줄 수 있어요. 생성되는 로그는 검색 요청 슬로우 로그보다 더 장황해요. 트러블슈팅이나 성능 튜닝을 위해서는 일시적으로만 활성화하는 걸 고려하세요. 샤드 슬로우 로그를 비활성화하려면 모든 임계값을 -1로 되돌리면 돼요. {: .important}

태스크 로그

태스크 리소스 컨슈머를 활성화하면 OpenSearch가 메모리를 가장 많이 쓰는 상위 N개 검색 태스크의 CPU 시간과 메모리 사용률을 기록할 수 있어요. 기본적으로 태스크 리소스 컨슈머는 60초 간격으로 상위 10개 검색 태스크를 기록해요. 이 값들은 opensearch.yml에서 설정할 수 있어요.

태스크 로깅은 Cluster Settings API를 통해 동적으로 활성화해요:

PUT _cluster/settings
{
  "persistent" : {
    "task_resource_consumers.enabled" : "true"
  }
}

{% include copy-curl.html %}

태스크 리소스 컨슈머를 활성화하면 검색 지연 시간에 영향을 줄 수 있어요. {:.tip}

활성화하고 나면 로그가 logs/opensearch_task_detailslog.json과 logs/opensearch_task_detailslog.log에 기록돼요.

로깅 간격과 기록할 검색 태스크 수를 설정하려면 opensearch.yml에 다음 줄을 추가하세요:

# Number of expensive search tasks to log
cluster.task.consumers.top_n.size:100

# Logging interval
cluster.task.consumers.top_n.frequency:30s

{% include copy.html %}

지원 중단 로그

지원 중단 로그는 클라이언트가 클러스터로 지원 중단된 API 호출을 보낼 때 기록돼요. 이 로그는 새 메이저 버전으로 업그레이드하기 전에 문제를 파악하고 수정하는 데 도움이 돼요. 기본적으로 OpenSearch는 지원 중단된 API 호출을 WARN 레벨로 기록하는데, 이 설정은 거의 모든 사용 사례에서 잘 동작해요. 원한다면 _cluster/settings, opensearch.yml, log4j2.properties를 사용해 logger.deprecation.level을 설정할 수 있어요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/install-and-configure/configuring-opensearch/logs/

Logs

본문

로그

애플리케이션 로그

공통 코어 로깅 카테고리

플러그인 로거 카테고리

에러 로그

매퍼 파싱 예외 범위

검색 요청 슬로우 로그

샤드 슬로우 로그

태스크 로그

지원 중단 로그

더 알아보기 (Learn more)

함께 읽는 실무 이야기