• English日本語한국어
  • 로그인지금 시작하기

Java 에이전트 구성: 구성 파일

뉴렐릭 Java 에이전트는 newrelic.yml 파일에서 구성을 읽습니다. 기본적으로 에이전트는 newrelic.jar가 포함된 디렉토리에서 이 파일을 찾습니다. newrelic.config.file 시스템 속성을 정규화된 파일 이름으로 설정하여 구성 파일의 위치를 재정의할 수 있습니다.

뉴렐릭 계정(영구 무료)을 만들고 Java 에이전트를 설치한 후 환경에 맞게 Java 에이전트를 구성할 수 있습니다.

구성 파일 구조

newrelic.yml 파일은 다양한 환경에 해당하는 스탠자로 분할됩니다.

  • 테스트
  • 개발
  • 스테이징
  • 프로덕션(기본값)

New Relic은 공통 스탠자의 설정을 이러한 환경 각각에 적용합니다. newrelic.environment 시스템 속성을 환경 이름으로 설정하여 다른 환경을 기본값으로 선택할 수 있습니다.

팁

newrelic.yml 템플릿을 사용할 수 있습니다.

newrelic.yml을 편집하는 경우, YAML 형식을 준수하도록 주의하십시오. 뉴렐릭의 Java 에이전트와 함께 파일을 사용하기 전에 YAML 유효성 검사기를 사용하여 구문이 정확한지 확인하고 다음 규칙을 따릅니다.

Java agent newrelic.yml

요구 사항

포맷

YML 파일은 대소문자를 구분합니다.

들여쓰기

모든 들여쓰기는 2자씩 증가해야 합니다. 다른 들여쓰기는 에이전트 시작 시 Unable to parse configuration file 오류를 발생시킵니다.

  • 파일의 동일한 스탠자에 있는 데이터에 대해 동일한 수준의 들여쓰기를 사용합니다.
  • 하위 조항을 추가로 2칸 들여씁니다.

파일 변경 사항

변경 사항을 적용하려면 JVM 호스트 프로세스를 다시 시작해야 합니다.

예외: log_level 및 audit_mode에 대한 속성 변경은 다시 시작할 필요가 없습니다. 서킷 브레이커에서의 속성 변경은 재시작이 필요하지 않습니다.

구성 설정 우선순위

구성 파일의 설정을 재정의하려면 시스템 속성 재정의를 사용합니다. 특정 환경에서는 환경 변수를 사용하여 구성 파일과 시스템 속성을 모두 재정의할 수도 있습니다. 환경 변수는 주로 Heroku를 지원하기 위해 존재합니다. 사용하면 서버 측 구성이 다른 모든 구성 설정보다 우선 적용됩니다.

Java 에이전트를 사용하면 서버 측 구성이 다른 모든 설정을 재정의합니다. 환경 변수는 Java 시스템 속성을 재정의합니다. 자바 속성은 newrelic.yml 파일의 사용자 구성 설정을 재정의합니다. 사용자 설정은 newrelic.yml 기본 설정보다 우선합니다.

Java 확장 디렉터리 구성

Java 에이전트는 프로세스 시작 시 구성 파일을 읽습니다. 파일이 있는 디렉터리를 식별하려면 새 디렉터리를 생성하거나 기존 확장 디렉터리를 지정하십시오.

일반 구성 설정

common 스탠자에서 이러한 옵션을 설정합니다. 이러한 옵션을 재정의하려면 newrelic.config 접두사가 붙은 시스템 속성을 사용합니다.

중요

Java 에이전트 3.48.0부터 SSL은 기본적으로 활성화되어 있으며 비활성화하는 구성 옵션은 더 이상 사용되지 않습니다. Java 에이전트 4.0.0부터 SSL을 비활성화하는 기능이 제거되었습니다.

환경 변수

환경 변수가 가장 높은 우선순위를 가지며 시스템 속성 및 yml 구성 설정을 재정의합니다.

  • 환경 변수를 설정하려면 export VARNAME=value 명령을 사용합니다.
  • 환경 변수를 영구적으로 설정하려면 내보내기 행을 ~/.bashrc 또는 ~/.bash_profile 같은 파일에 추가합니다.

환경 변수를 설정하여 시스템 속성 또는 newrelic.yml의 모든 설정을 재정의할 수 있습니다. 구성 파일의 지정된 설정에 해당하는 환경 변수는 모든 점( . ) 및 대시( - )가 밑줄( _ )로 대체된 NEW_RELIC 접두사가 붙은 설정 이름입니다. 예를 들어, log_level 설정에 대한 환경 변수는 NEW_RELIC_LOG_LEVEL입니다.

스탠자에 중첩된 설정의 경우 스탠자 이름을 설정 이름 앞에 추가합니다. 예를 들어,

class_transformer:
    com.newrelic.instrumentation.kafka-clients-spans-0.11.0.0:
      enabled: true

위의 구성은 다음과 같은 환경 변수로 변환됩니다. NEW_RELIC_CLASS_TRANSFORMER_COM_NEWRELIC_INSTRUMENTATION_KAFKA_CLIENTS_SPANS_0_11_0_0_ENABLED

중요

환경 변수를 통한 에이전트 구성에는 Java 에이전트 버전 4.10.0 이상이 필요합니다.

시스템 속성

시스템 속성을 설정하여 newrelic.yml 파일의 모든 설정을 재정의할 수 있습니다. 구성 파일의 지정된 설정에 해당하는 시스템 속성은 newrelic.config 접두사가 붙은 설정 이름입니다. 예를 들어, log_level 설정의 시스템 속성은 newrelic.config.log_level입니다.

스탠자에 중첩된 설정의 경우, 스탠자 이름을 설정 이름 앞에 추가합니다. 예를 들어, transaction_tracer 스탠자의 enabled 설정에 대한 시스템 속성은 newrelic.config.transaction_tracer.enabled 입니다.

구성 설정을 재정의하는 것 외에도 에이전트는 다음 시스템 속성을 인식합니다.

속성

이러한 옵션을 설정하려면 attributes 스탠자를 사용합니다. 이를 재정의하려면 newrelic.config.attributes 접두사가 붙은 시스템 속성을 사용합니다.

속성은 트랜잭션 추적, 추적된 오류, 브라우저 모니터링 및 트랜잭션 이벤트에 대한 정보를 제공하는 키-값 쌍입니다. 또한 각 대상 아래에 속성 스탠자가 있습니다. 자세한 내용은 Java 에이전트 속성, 속성 활성화 및 비활성화 및 속성 예제를 참조하십시오.

비동기 계측

이러한 옵션은 common 스탠자에서 직접 설정되며 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

브라우저 모니터링

이러한 옵션은 browser_monitoring 스탠자에 설정되며 newrelic.config.browser_monitoring 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

브라우저 모니터링은 실제 사용자가 웹사이트에서 경험하고 있는 성능에 대한 통찰력을 제공합니다. 이는 각 페이지의 머리글과 바닥글에 소량의 JavaScript 코드를 삽입하여 사용자의 브라우저가 웹 페이지를 다운로드하고 렌더링하는 데 걸리는 시간을 측정하여 수행됩니다.

Circuit breaker

이러한 설정은 Java 서킷 브레이커의 동작을 사용자 정의합니다. 이러한 설정은 기본적으로 newrelic.yml에 포함되지 않습니다. JVM을 변경한 후 JVM을 다시 시작할 필요가 없습니다.

서킷 브레이커를 맞춤화하려면 common 스탠자 아래에 스탠자를 추가합니다.

common: &default_settings​
  OTHER_CONFIG_SETTINGS
  circuitbreaker:
    enabled: true
    memory_threshold: 20
    gc_cpu_threshold: 10

클라우드 플랫폼 활용

이러한 옵션은 utilization 스탠자에 설정되며 newrelic.config.utilization 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

에이전트는 활용 정보를 수집하여 뉴렐릭 서비스로 전송합니다. 에이전트는 Amazon Web Services(AWS), Azure, Google Cloud Platform 및 Pivotal Cloud Foundry 인스턴스에서 정보를 수집할 수 있습니다. 또한 도커 컨테이너와 쿠버네티스 서비스와 관련된 정보도 수집합니다.

코드 레벨 메트릭

코드 레벨 메트릭은 코드가 메서드 수준에서 수행되는 방식에 대한 세부적인 인사이트를 제공합니다. 자동으로 계측되거나 @Trace 주석으로 계측된 각 메서드에 대한 메트릭이 표시됩니다. 코드 레벨 메트릭에 대한 보다 자세한 내용은 CodeStream을 사용한 성능 모니터링을 참조하십시오.

코드 레벨 메트릭 옵션은 code_level_metrics 스탠자에 설정되며 newrelic.config.code_level_metrics 접두사가 있는 시스템 속성을 사용하여 재정의할 수 있습니다.

에러스 인박스 구성

다음 태그 중 하나를 설정하면 오류를 생성하는 소프트웨어 버전을 식별하는 데 도움이 됩니다.

  • NEW_RELIC_METADATA_SERVICE_VERSION 배포된 코드 버전(대부분의 경우 1.2.3으로 표시되는 버전)이 포함된 이벤트 데이터에 대해 tagged.service.version이 생성되지만 항상 그런 것은 아닙니다.
  • NEW_RELIC_METADATA_RELEASE_TAG 릴리스 태그(예: v0.1.209 또는 릴리스-209)가 포함된 이벤트 데이터에 tagged.releaseTag를 생성합니다.
  • NEW_RELIC_METADATA_COMMIT 커밋 SHA를 포함하는 이벤트 데이터에 대해 tagged.commit을 생성합니다. 전체 SHA를 사용하거나 처음 7자만 사용할 수 있습니다. (예: 734713b)

향후에 릴리스될 에러스 인박스는 오류를 생성하는 소프트웨어 버전을 자동으로 추적합니다. 모든 버전 데이터는 CodeStream에도 표시됩니다.

애플리케이션 간 추적기

중요

애플리케이션 간 추적은 에이전트 버전 7.4.0부터 더 이상 사용되지 않으며 향후 에이전트 버전에서 삭제될 예정입니다.

애플리케이션 간 추적을 사용하는 대신 분산 추적 기능을 사용하시길 권합니다. 분산 추적은 애플리케이션 간 추적 기능을 개선한 것으로 대규모 분산 시스템에 권장됩니다.

교차 애플리케이션 추적 옵션은 cross_application_tracer 스탠자에 설정되며 newrelic.config.cross_application_tracer 접두사가 있는 시스템 속성을 사용하여 재정의할 수 있습니다.

애플리케이션 간 추적(Cross application tracing)은 Apache HttpClient 라이브러리를 사용해 외부 호출에 요청 및 응답 헤더를 추가합니다. 이는 다른 뉴렐릭 에이전트가 모니터링하는 애플리케이션을 호출할 때 더 나은 성능 데이터를 제공합니다.

커스텀 이벤트

커스텀 이벤트는 custom_insights_events 스탠자에서 설정되며 newrelic.config.custom_insights_events 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

APM을 사용하면 뉴렐릭 언어 에이전트 API를 통해 커스텀 이벤트 데이터를 기록할 수 있습니다.

중요

4.1.0 이전 Java 에이전트 버전의 경우 다음 YAML 구성이 인식됩니다.

custom_insights_events.enabled: true
  custom_insights_events.max_samples_stored: 5000

에이전트 버전 4.1.0 이상의 경우 YAML 구성은 중첩 스탠자 형식을 사용합니다.

custom_insights_events:
  enabled: false
  max_samples_stored: 5000

맞춤형 계측

이러한 옵션은 class_transformer 스탠자에 설정되며 newrelic.config.class_transformer 접두사가 있는 시스템 속성을 사용하여 재정의할 수 있습니다.

분산 추적

중요

분산 추적을 활성화하면 교차 애플리케이션 추적이 비활성화되고 APM 기능에 다른 영향을 미칩니다. 활성화하기 전에 전환 가이드를 확인하시기 바랍니다.

Java 에이전트 버전 4.3.0 이상이 필요합니다.

분산 추적은 분산 시스템을 통해 이동하는 요청의 경로를 볼 수 있도록 해줍니다. 이 기능은 Java 에이전트 버전 7.4.0 이상에서 기본적으로 활성화되어 있습니다.

구성 파일의 distributed_tracing 스탠자에서 이를 수동으로 재정의할 수 있습니다. 접두사 시스템 속성(newrelic.config.distributed_tracing) 또는 환경 변수(NEW_RELIC_DISTRIBUTED_TRACING_ENABLED)를 사용하여 이를 재정의할 수도 있습니다. 아래의 예를 참조하십시오.

분산 추적 설정에 대한 보다 자세한 정보는 Java 애플리케이션에 대한 분산 추적 사용을 참조하십시오.

오류 수집기

이러한 옵션은 error_collector 스탠자에 설정되며 달리 명시되지 않는 한 newrelic.config.error_collector 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다. 오류 수집기는 포착되지 않은 예외에 대한 정보를 캡처하고 볼 수 있도록 이를 뉴렐릭으로 보냅니다.

팁

UI를 통해 오류를 구성하는 방법을 포함하여 Java 에이전트에 대한 오류를 구성하는 방법은 Java 에이전트 오류 구성을 참조하십시오.

외부 추적기

외부 추적 옵션은 external_tracer 스탠자에 설정되며 newrelic.config.external_tracer 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

호스트 이름 구성

이러한 옵션은 process_host 스탠자에 설정되며 newrelic.config.process_host 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

다음 속성은 UI에 표시되는 호스트 이름을 구성하는 데 사용됩니다.

Infinite Tracing

중요

요구 사항:

Infinite Tracing(무한 추적)을 켜려면, 분산 추적을 활성화하고 아래에 추가 설정을 추가합니다. 예시는 언어 에이전트: 분산 추적 구성을 참조하십시오.

Jar 수집기

Java 에이전트는 애플리케이션 클래스 경로에서 jar 및 해당 버전에 대한 정보를 수집합니다.

Jar 컬렉션 구성은 jar_collector 스탠자에 설정되며 newrelic.config.jar_collector 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다. 옵션에는 다음이 포함됩니다.

JFR(실시간 프로파일링)

Java 에이전트는 JFR(Java Flight Recorder)을 사용하여 실시간 프로파일링을 위해 충실도가 높은 JVM 데이터를 수집합니다.

에이전트 yaml의 jfr 스탠자에서 실시간 프로파일링을 구성할 수 있으며, 시스템 속성은 접두사 newrelic.config.jfr. 또는 환경 변수는 접두사 NEW_RELIC_JFR_입니다.

JMX

이러한 옵션을 설정하려면 jmx 스탠자를 사용합니다. 이를 재정의하려면 newrelic.config.jmx 접두사가 붙은 시스템 속성을 사용합니다.

Java 에이전트는 JMX를 사용하여 JVM 데이터를 수집합니다. 또한 에이전트는 다른 추적 시스템에서 사용할 수 있는 JMX를 통해 연결 메타데이터를 노출할 수 있습니다.

문맥적 로그(Logs in context)

Java 에이전트 버전 7.6.0부터 문맥적 로그 지원이 에이전트에 추가되어 지원되는 로깅 프레임워크에 쉽게 사용할 수 있습니다. 문맥적 로그에 Java 에이전트를 사용하는 방법에 대한 팁은 문맥적 Java 로그를 참조하십시오.

로컬 에이전트 구성 파일에서의 설정 변경은 동적으로 이루어지며, 변경 사항을 적용하기 위해 에이전트를 다시 시작할 필요가 없습니다. 구성 예시:

application_logging:
  enabled: true
  forwarding:
    enabled: true
    max_samples_stored: 10000
    context_data:
      enabled: false
      include:
      exclude:
  metrics:
    enabled: true
  local_decorating:
      enabled: false

문맥적 로그 설정은 application_logging 스탠자에 설정되며 newrelic.config.application_logging 접두사가 있는 시스템 속성을 사용하여 재정의할 수 있습니다. 사용 가능한 유일한 옵션은 다음과 같습니다.

로그 전달

지원되는 로깅 프레임워크를 사용 중이고 에이전트를 사용하여 애플리케이션 로그를 뉴렐릭으로 보내려는 경우, newrelic.config.application_logging.forwarding 접두사가 붙은 시스템 속성으로 재정의할 수 있는 forwarding 스탠자 아래의 설정을 통해 이를 제어할 수 있습니다. 사용 가능한 옵션은 다음과 같습니다.

로그 컨텍스트 데이터

Java 에이전트는 컨텍스트 데이터(logback/slf4j에 Mapped Diagnostic Context(매핑된 진단 컨텍스트), log4j2의 ThreadContext)를 캡처하고 해당 콘텐츠를 뉴렐릭에 전달되는 로그의 속성으로 추가할 수 있습니다. forwarding 스탠자 하단에 중첩된 context_data 스탠자 아래에서 설정을 통해 이를 제어할 수 있습니다. 이러한 설정은 newrelic.config.application_logging.forwarding.context_data 접두사가 붙은 시스템 속성으로 재정의할 수 있습니다. 사용 가능한 옵션은 다음과 같습니다.

로그 메트릭

개별 로그 라인을 데코레이팅하고 전송할 수 있을 뿐만 아니라 Java 에이전트는 뉴렐릭 UI의 로그 차트에 표시되는 로깅 메트릭 데이터도 캡처할 수 있습니다. 이는 metrics 스탠자 아래의 설정으로 제어되며 newrelic.config.application_logging.metrics 접두사가 붙은 시스템 속성으로 재정의할 수 있습니다. 사용 가능한 유일한 옵션은 다음과 같습니다.

로그 장식

local_decorating 스탠자를 사용하면 로컬 로그 줄 데코레이팅을 제어할 수 있으며 newrelic.config.application_logging.local_decorating 접두사가 붙은 시스템 속성으로 재정의할 수 있습니다. 사용 가능한 유일한 옵션은 다음과 같습니다.

로깅 구성

이는 일반 구성 변수의 일부입니다. 디버깅을 위해 자주 조정되기 때문에 여기에서 분류됩니다.

일부 로깅 구성 변수는 동적이며 적용하기 위해 호스트를 다시 시작할 필요가 없습니다. 예를 들어, 로그 파일이 너무 빨리 증가하는 경우 log_level을 덜 자세한 설정으로 설정하여 보고율을 줄일 수 있습니다.

다음은 로그 회전에 영향을 미치는 구성 변수의 우선순위와 설명입니다.

  • log_daily가 true인 경우:

    • log_limit_in_kbytes 값이 0보다 크면 복합 트리거링 정책이 야기됩니다. 이는 로그가 하루에 한 번 또는 정해진 크기에 도달하면 롤링이 되며, 최대 log_file_count 파일을 유지합니다.
    • log_limit_in_kbytes 값이 0이면 로그가 하루에 한 번 롤링되어 최대 log_file_count 개의 파일을 유지합니다.

  • log_daily가 false이고 log_limit_in_kbytes > 0인 경우 크기 기반 정책이 설정되며, 정의된 크기에 도달하면 로그가 롤링되어 최대 log_file_count개의 파일을 유지합니다.

  • log_daily가 false이고 log_limit_in_kbytes = 0이면 로그 파일 롤링 논리가 설정되지 않습니다.

증가율에 따라 로그 파일 크기가 설정된 값을 약간 초과할 수 있습니다.

메시지 추적기

이러한 옵션은 message_tracer 스탠자에 설정되며 newrelic.config.message_tracer 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

보안 에이전트

뉴렐릭의 보안 에이전트인 인터랙티브 애플리케이션 보안 테스트(IAST)는 생성된 HTTP 요청을 취약한 페이로드와 함께 재생하여 악용 가능한 취약점이 있는지 애플리케이션을 테스트합니다.

중요

프로덕션 소프트웨어에 취약점이 노출되지 않도록 비프로덕션 배포에서만 IAST를 실행하십시오.

뉴렐릭 보안 에이전트 구성은 security 스탠자에서 설정되며 newrelic.config.security 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다. 옵션은 다음과 같습니다.

중요

뉴렐릭 보안 에이전트 IAST(Interactive Applications Security Testing) 모드는 Java 에이전트 버전 8.4.0 이상이 필요합니다.

느린 트랜잭션 감지

이제 Java 에이전트 버전 8.7.0 이후 에이전트는 SlowTransaction 이벤트를 통해 느린 트랜잭션을 감지할 수 있습니다. 이러한 이벤트는 트랜잭션 길이가 특정 임계값을 초과할 때 기록됩니다. 기본적으로 임계값은 1000밀리초입니다.

느린 트랜잭션 감지는 slow_transactions으로 설정되며 newrelic.config.slow_transactions 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다. 옵션은 다음과 같습니다:

스팬 이벤트

분산 추적에 대한 스팬 이벤트가 보고됩니다. 스팬 이벤트를 보고하려면 분산 추적을 활성화해야 합니다.

스팬 구성은 span_events 스탠자에서 설정되며 newrelic.config.span_events 접두사가 있는 시스템 속성을 사용하여 재정의할 수 있습니다. 옵션에는 다음이 포함됩니다.

중요

스팬 이벤트 속성 필터링에는 Java 에이전트 버전 4.10.0 이상이 필요합니다.

스트립 예외

이러한 옵션은 strip_exception_messages 스탠자에 설정되며 달리 명시되지 않는 한 newrelic.config.strip_exception_messages 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다. 이 구성을 사용하여 Java 예외 메시지가 뉴렐릭에 보고되는지 여부를 제어할 수 있습니다.

스레드 프로파일러

이러한 옵션은 thread_profiler 스탠자에 설정되며 newrelic.config.thread_profiler 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

스레드 프로파일러는 애플리케이션 스레드가 실행될 때 wall clock time, CPU 시간 및 메서드 호출 수를 측정합니다.

트랜잭션 이벤트

이러한 옵션은 transaction_events 스탠자에 설정되며 newrelic.config.transaction_events 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

트랜잭션 이벤트는 UI에 히스토그램과 백분위수를 표시하기 위한 데이터를 제공합니다.

중요

이전에는 이 스탠자를 analytics_events라고 했습니다. 구성 파일이 여전히 analytics_events를 사용하는 경우, transaction_events를 사용하도록 에이전트를 업데이트하십시오.

트랜잭션 세그먼트

이러한 옵션은 transaction_segments 스탠자에 설정되며 newrelic.config.transaction_segments 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

트랜잭션 세그먼트는 개별 작업(일반적으로 메서드 호출)을 나타내며 트랜잭션 트레이스 내에 표시됩니다.

중요

트랜잭션 세그먼트 속성 필터링을 사용하려면 Java 에이전트 버전 4.10.0 이상이 필요합니다.

트랜잭션 추적기

이러한 옵션은 transaction_tracer 스탠자에 설정되며 newrelic.config.transaction_tracer 접두사가 붙은 시스템 속성을 사용하여 재정의할 수 있습니다.

트랜잭션 추적은 느린 트랜잭션에 대한 심층 정보를 캡처하고 이를 뉴렐릭 서비스로 보냅니다. 트랜잭션에는 발행된 쿼리 문을 포함하여 트랜잭션의 정확한 호출 순서가 포함됩니다.

중요

트랜잭션 이름 끝에 대괄호 [suffix]를 사용하지 마십시오. 뉴렐릭은 자동으로 이름에서 괄호를 제거합니다. 대신 필요한 경우 괄호 (suffix) 또는 기타 기호를 사용합니다.

Copyright © 2023 New Relic Inc.
채용정보서비스 이용약관DMCA 정책개인정보 고지쿠키 정책영국 현대판 노예법

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.