원격 분석 프로세서(미리 보기) - Java용 Azure Monitor Application Insights

  • 아티클

참고 항목

원격 분석 프로세서 기능은 특성 의미 체계 규칙의 실험 상태로 인해 릴리스 간에 이전 버전과의 호환성을 보장할 수 없으므로 미리 보기로 지정되었습니다. 그러나 이 기능은 테스트되었으며 프로덕션에서 지원됩니다.

Application Insights Java 3.x는 데이터를 내보내기 전에 원격 분석 데이터를 처리할 수 있습니다.

일부 사용 사례:

  • 중요한 데이터를 마스크합니다.
  • 조건부로 사용자 지정 차원을 추가합니다.
  • Azure Portal에서 유사한 원격 분석을 집계하는 데 사용되는 범위 이름을 업데이트합니다.
  • 특정 범위 특성을 삭제하여 수집 비용을 제어합니다.
  • 일부 메트릭을 필터링하여 수집 비용을 제어합니다.

참고 항목

수집 비용을 제어하기 위해 특정(전체) 범위를 삭제하려는 경우 샘플링 재정의를 참조하세요.

용어

원격 분석 프로세서에 대해 알아보기 전에 ‘범위’ 및 ‘로그’라는 용어를 이해해야 합니다.

범위는 다음 중 하나를 나타내는 원격 분석 유형입니다.

  • 들어오는 요청.
  • 나가는 종속성(예: 다른 서비스에 대한 원격 호출).
  • In-process 종속성(예: 서비스의 하위 구성 요소에 의해 수행되는 작업).

로그는 다음을 나타내는 원격 분석 유형입니다.

  • Log4j, Logback 및 java.util.logging에서 캡처된 로그 데이터

원격 분석 프로세서의 경우 다음 범위/로그 구성 요소가 중요합니다.

  • 이름
  • 본문
  • 특성

범위 이름은 Azure Portal의 요청 및 종속성에 대한 기본 디스플레이입니다. 범위 특성은 지정된 요청 또는 종속성의 표준 및 사용자 지정 속성을 모두 나타냅니다.

추적 메시지 또는 본문은 Azure Portal에서 로그에 대한 기본 표시입니다. 로그 특성은 지정된 로그의 표준 및 사용자 지정 속성을 모두 나타냅니다.

원격 분석 프로세서 유형

현재 네 가지 유형의 원격 측정 프로세서는 다음과 같습니다.

  • 특성 프로세서
  • 스팬 프로세서
  • 로그 프로세서
  • 메트릭 필터

특성 프로세서는 원격 분석 항목(span 또는 log)의 특성을 삽입, 업데이트, 삭제 또는 해시할 수 있습니다. 정규식을 사용하여 기존 특성에서 하나 이상의 새 특성을 추출할 수도 있습니다.

범위 프로세서는 요청 및 의존성의 원격 분석 이름을 업데이트할 수 있습니다. 정규식을 사용하여 범위 이름에서 하나 이상의 새 특성을 추출할 수도 있습니다.

로그 프로세서는 로그의 원격 분석 이름을 업데이트할 수 있습니다. 정규식을 사용하여 로그 이름에서 하나 이상의 새 특성을 추출할 수도 있습니다.

메트릭 필터는 메트릭을 필터링하여 수집 비용을 제어할 수 있습니다.

참고 항목

현재 원격 분석 프로세서는 문자열 형식의 특성만 처리합니다. 부울 또는 숫자 형식의 특성은 처리하지 않습니다.

시작하기

시작하려면 applicationinsights.json이라는 구성 파일을 만듭니다. 이를 동일한 디렉터리에 applicationinsights-agent-*.jar로 저장합니다. 다음 템플릿을 사용합니다.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

특성 프로세서

특성 프로세서는 span 또는 log의 특성을 수정합니다. span 또는 log를 포함하거나 제외하는 기능을 지원할 수 있습니다. 구성 파일에서 지정하는 순서대로 수행되는 작업 목록을 사용합니다. 프로세서는 다음 작업을 지원합니다.

  • insert
  • update
  • delete
  • hash
  • extract
  • mask

insert

insert 작업은 key가 아직 없는 원격 분석 항목에 새 특성을 삽입합니다.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

insert 작업은 다음 설정이 필요합니다.

  • key
  • value 또는 fromAttribute 중 하나입니다.
  • action: insert

update

update 작업은 key가 이미 있는 원격 분석 항목의 특성을 업데이트합니다.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

update 작업은 다음 설정이 필요합니다.

  • key
  • value 또는 fromAttribute 중 하나입니다.
  • action: update

delete

delete 작업은 원격 분석 항목에서 특성을 삭제합니다.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

delete 작업은 다음 설정이 필요합니다.

  • key
  • action: delete

hash

hash 작업은 기존 특성 값을 해시(SHA1)합니다.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

hash 작업은 다음 설정이 필요합니다.

  • key
  • action: hash

extract

참고 항목

extract 기능은 버전 3.0.2 이상에서만 사용할 수 있습니다.

extract 작업은 입력 키에서 규칙을 지정하는 대상 키로 정규식 규칙을 사용하여 값을 추출합니다. 대상 키가 이미 있는 extract 경우 작업은 대상 키를 재정의합니다. 이 동작은 기존 특성이 원본인 범위 프로세서toAttributes 설정처럼 동작합니다.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

extract 작업은 다음 설정이 필요합니다.

  • key
  • pattern
  • action: extract

mask

참고 항목

mask 기능은 버전 3.2.5 이상에서만 사용할 수 있습니다.

mask 작업은 pattern 및 replace에 지정된 정규식 규칙을 사용하여 특성 값을 마스킹합니다.

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

mask 작업은 다음 설정이 필요합니다.

  • key
  • pattern
  • replace
  • action: mask

pattern은(는) ?<에서 >: 사이에 배치되어 명명된 그룹을 포함할 수 있습니다. 예: (?<userGroupName>[a-zA-Z.:\/]+)\d+? 그룹은 (?<userGroupName>[a-zA-Z.:\/]+)이며 userGroupName은(는) 그룹의 이름입니다. pattern에 ${과(와) } 사이에 배치된 동일한 이름의 그룹과 그 다음에 마스크를 포함할 수 있습니다. 마스크가 **인 예제: ${userGroupName}**.

마스킹 예제는 원격 분석 프로세서 예제를 참조하세요.

include 조건 및 exclude 조건

특성 프로세서는 선택적 include 및 exclude 조건을 지원합니다. 특성 프로세서는 해당 조건(사용 가능한 경우)과 일치 include 하고 해당 조건과 일치하지 exclude 않는 원격 분석에만 적용됩니다(사용 가능한 경우).

이 옵션을 구성하려면 include 또는 exclude(또는 둘 다)에서 matchType 및 spanNames이나 attributes 중 하나 이상을 지정합니다. include 또는 exclude 구성에서 둘 이상의 지정된 조건을 허용합니다. 일치하는 결과를 얻으려면 지정된 모든 조건이 true로 평가되어야 합니다.

  • 필수 필드:

    • matchType는 배열 및 attributes 배열의 spanNames 항목을 해석하는 방법을 제어합니다. 가능한 값은 regexp 및 strict입니다. 정규식 일치는 전체 특성 값에 대해 수행되므로 abc를 포함한 값을 일치시키려면 .*abc.*를 사용해야 합니다.

  • 선택적 필드:

    • spanNames는 하나 이상의 항목과 일치해야 합니다.
    • attributes는 일치시킬 특성 목록을 지정합니다. 일치하는 결과를 얻으려면 이러한 특성은 모두 정확히 일치해야 합니다.

참고 항목

include 및 exclude 모두 지정하는 경우 exclude 속성이 확인되기 전에 include 속성이 확인됩니다.

참고 항목

include 또는 exclude 구성에 spanNames가 지정되지 않은 경우 일치 조건이 spans 및 logs 둘 다에 적용됩니다.

샘플 사용

"processors": [
  {
    "type": "attribute",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "redact_trace",
          "value": "false"
        }
      ]
    },
    "actions": [
      {
        "key": "credit_card",
        "action": "delete"
      },
      {
        "key": "duplicate_key",
        "action": "delete"
      }
    ]
  }
]

자세한 내용은 원격 분석 프로세서 예시를 참조하세요.

범위 프로세서

범위 프로세서는 범위 이름 또는 범위 이름을 기반으로 범위의 특성을 수정합니다. 이는 범위를 포함하거나 제외하는 기능을 지원할 수 있습니다.

범위 이름 지정

name 섹션은 fromAttributes 설정이 필요합니다. 이러한 특성 값은 구성에서 지정하는 순서로 연결된 새 이름을 만드는 데 사용됩니다. 프로세서는 이러한 특성이 모두 범위에 있는 경우에만 범위 이름을 변경합니다.

separator 설정은 선택 사항입니다. 이 설정은 문자열이며 분할 값을 사용할 수 있습니다.

참고 항목

이름 바꾸기가 특성 프로세서를 사용하여 특성을 수정하는 경우 파이프라인 사양의 특성 프로세서가 지정된 후에 범위 프로세서가 지정되었는지 확인합니다.

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

범위 이름에서 특성 추출

toAttributes 섹션에서는 범위 이름과 일치하는 정규식을 나열합니다. 하위 식을 기반으로 특성을 추출합니다.

rules 설정이 필요합니다. 이 설정은 범위 이름에서 특성 값을 추출하는 데 사용되는 규칙을 나열합니다.

추출된 특성 이름은 범위 이름의 값을 바꿉니다. 목록의 각 규칙은 정규식(regex) 패턴 문자열입니다.

추출된 특성 이름이 값을 대체하는 방법은 다음과 같습니다.

  1. 범위 이름이 정규식에 대해 확인됩니다.
  2. regex가 일치하는 경우 regex의 모든 명명된 하위 식이 특성으로 추출됩니다.
  3. 추출된 특성이 범위에 추가됩니다.
  4. 각 하위 식 이름은 특성 이름이 됩니다.
  5. 하위 식과 일치하는 부분은 특성 값이 됩니다.
  6. 추출된 특성 이름은 범위 이름에서 일치하는 부분을 대체합니다. 특성이 범위에 이미 있는 경우 해당 특성을 덮어씁니다.

이 프로세스는 지정된 순서대로 모든 규칙에 대해 반복됩니다. 각 후속 규칙은 이전 규칙의 출력인 범위 이름에 대해 작동합니다.

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

공통 범위 특성

이 섹션에서는 원격 분석 프로세서에서 사용할 수 있는 몇 가지 공통 범위 특성이 나열됩니다.

HTTP 범위

Attribute Type 설명
http.request.method(사용)http.method string HTTP 요청 메서드입니다.
url.full(클라이언트 범위) 또는 url.path (서버 범위) (사용)http.url string scheme://host[:port]/path?query[#fragment] 형식의 전체 HTTP 요청 URL. 조각은 일반적으로 HTTP를 통해 전송되지 않습니다. 하지만 조각이 알려져 있는 경우 이를 포함해야 합니다.
http.response.status_code(사용)http.status_code 번호 HTTP 응답 상태 코드입니다.
network.protocol.version(사용)http.flavor string HTTP 프로토콜의 유형입니다.
user_agent.original(사용)http.user_agent string 클라이언트에서 보낸 HTTP 사용자 에이전트 헤더의 값입니다.

Java Database 커넥트ivity 범위

다음 표에서는 JDBC(Java Database 커넥트ivity) 범위에서 사용할 수 있는 특성을 설명합니다.

attribute Type 설명
db.system string 사용 중인 DBMS(데이터베이스 관리 시스템) 제품의 식별자입니다. 데이터베이스 작업에 대한 의미 체계 규칙을 참조하세요.
db.connection_string string 데이터베이스에 연결하는 데 사용되는 연결 문자열입니다. 포함된 자격 증명을 제거하는 것이 좋습니다.
db.user string 데이터베이스에 액세스하기 위한 사용자 이름입니다.
db.name string 액세스 중인 데이터베이스의 이름을 보고하는 데 사용되는 문자열입니다. 데이터베이스를 전환하는 명령의 경우 명령이 실패하더라도 이 문자열을 대상 데이터베이스로 설정해야 합니다.
db.statement string 실행 중인 데이터베이스 문입니다.

include 조건 및 exclude 조건

범위 프로세서는 선택적 include 및 exclude 조건을 지원합니다. 범위 프로세서는 해당 조건(사용 가능한 경우)과 일치 include 하고 해당 조건과 일치하지 exclude 않는 원격 분석에만 적용됩니다(사용 가능한 경우).

이 옵션을 구성하려면 include 또는 exclude(또는 둘 다)에서 하나 이상의 matchType과 spanNames 또는 범위 attributes를 지정합니다. include 또는 exclude 구성에서 둘 이상의 지정된 조건을 허용합니다. 일치하는 결과를 얻으려면 지정된 모든 조건이 true로 평가되어야 합니다.

  • 필수 필드:

    • matchType는 배열 및 attributes 배열의 spanNames 항목을 해석하는 방법을 제어합니다. 가능한 값은 regexp 및 strict입니다. 정규식 일치는 전체 특성 값에 대해 수행되므로 abc를 포함한 값을 일치시키려면 .*abc.*를 사용해야 합니다.

  • 선택적 필드:

    • spanNames는 하나 이상의 항목과 일치해야 합니다.
    • attributes는 일치시킬 특성 목록을 지정합니다. 일치하는 결과를 얻으려면 이러한 특성은 모두 정확히 일치해야 합니다.

참고 항목

include 및 exclude 모두 지정하는 경우 exclude 속성이 확인되기 전에 include 속성이 확인됩니다.

샘플 사용

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

자세한 내용은 원격 분석 프로세서 예시를 참조하세요.

로그 프로세서

참고 항목

로그 프로세서는 버전 3.1.1부터 사용할 수 있습니다.

로그 프로세서는 로그 메시지 본문 또는 로그 메시지 본문을 기준으로 하는 로그의 특성을 수정합니다. 로그를 포함하거나 제외하는 기능을 지원할 수 있습니다.

로그 메시지 본문 업데이트

body 섹션은 fromAttributes 설정이 필요합니다. 이러한 특성 값은 구성에서 지정하는 순서로 연결된 새 본문을 만드는 데 사용됩니다. 프로세서는 로그에 이 모든 특성이 있는 경우에만 로그 본문을 변경합니다.

separator 설정은 선택 사항입니다. 이 설정은 문자열입니다. 값을 분할하도록 지정할 수 있습니다.

참고 항목

이름 바꾸기가 특성 프로세서를 사용하여 특성을 수정하는 경우 파이프라인 사양의 특성 프로세서가 지정된 후에 로그 프로세서가 지정되었는지 확인합니다.

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

로그 메시지 본문에서 특성 추출

toAttributes 섹션에서는 로그 메시지 본문과 일치하는 정규식을 나열합니다. 하위 식을 기반으로 특성을 추출합니다.

rules 설정이 필요합니다. 이 설정은 본문에서 특성 값을 추출하는 데 사용되는 규칙을 나열합니다.

추출된 특성 이름은 로그 메시지 본문의 값을 대체합니다. 목록의 각 규칙은 정규식(regex) 패턴 문자열입니다.

추출된 특성 이름이 값을 대체하는 방법은 다음과 같습니다.

  1. 로그 메시지 본문이 정규식에 대해 검사됩니다.
  2. regex가 일치하는 경우 regex의 모든 명명된 하위 식이 특성으로 추출됩니다.
  3. 추출된 특성이 로그에 추가됩니다.
  4. 각 하위 식 이름은 특성 이름이 됩니다.
  5. 하위 식과 일치하는 부분은 특성 값이 됩니다.
  6. 추출된 특성 이름은 로그 이름에서 일치하는 부분을 대체합니다. 특성이 로그에 이미 있는 경우 해당 특성을 덮어씁니다.

이 프로세스는 지정된 순서대로 모든 규칙에 대해 반복됩니다. 각 후속 규칙은 이전 규칙의 출력인 로그 이름에 대해 작동합니다.

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

include 조건 및 exclude 조건

로그 프로세서는 선택적 include 및 exclude 조건을 지원합니다. 로그 프로세서는 해당 조건(사용 가능한 경우)과 일치 include 하고 해당 조건과 일치하지 exclude 않는 원격 분석에만 적용됩니다(사용 가능한 경우).

이 옵션을 구성하려면 include 또는 exclude(또는 둘 다)에서 matchType 및 attributes를 지정합니다. include 또는 exclude 구성에서 둘 이상의 지정된 조건을 허용합니다. 일치하는 결과를 얻으려면 지정된 모든 조건이 true로 평가되어야 합니다.

  • 필수 필드:
    • matchType은 attributes 배열의 항목을 해석하는 방법을 제어합니다. 가능한 값은 regexp 및 strict입니다. 정규식 일치는 전체 특성 값에 대해 수행되므로 abc를 포함한 값을 일치시키려면 .*abc.*를 사용해야 합니다.
    • attributes는 일치시킬 특성 목록을 지정합니다. 일치하는 결과를 얻으려면 이러한 특성은 모두 정확히 일치해야 합니다.

참고 항목

include 및 exclude 모두 지정하는 경우 exclude 속성이 확인되기 전에 include 속성이 확인됩니다.

참고 항목

로그 프로세서는 spanNames를 지원하지 않습니다.

샘플 사용

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

자세한 내용은 원격 분석 프로세서 예시를 참조하세요.

메트릭 필터

참고 항목

메트릭 필터는 버전 3.1.1부터 사용할 수 있습니다.

메트릭 필터는 수집 비용을 제어하기 위해 일부 메트릭을 제외하는 데 사용됩니다.

메트릭 필터는 exclude 조건만 지원합니다. 해당 exclude 조건과 일치하는 메트릭은 내보내지지 않습니다.

이 옵션을 구성하려면 exclude 아래에서 하나 이상의 matchTypemetricNames를 지정합니다.

  • 필수 필드:
    • matchType은 metricNames의 항목이 일치하는 방식을 제어합니다. 가능한 값은 regexp 및 strict입니다. 정규식 일치는 전체 특성 값에 대해 수행되므로 abc를 포함한 값을 일치시키려면 .*abc.*를 사용해야 합니다.
    • metricNames는 하나 이상의 항목과 일치해야 합니다.

샘플 사용

다음 샘플에서는 이름이 "metricA" 및 "metricB"인 메트릭을 제외하는 방법을 보여 줍니다.

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

다음 샘플에서는 cpu 및 메모리와 같은 기본 자동 수집 성능 메트릭을 포함하여 모든 메트릭을 해제하는 방법을 보여 줍니다.

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Java 에이전트에서 캡처한 기본 메트릭

메트릭 이름 메트릭 유형 설명 필터 가능
Current Thread Count 사용자 지정 메트릭 ThreadMXBean.getThreadCount()를 참조하세요. 예
Loaded Class Count 사용자 지정 메트릭 ClassLoadingMXBean.getLoadedClassCount()를 참조하세요. 예
GC Total Count 사용자 지정 메트릭 모든 GarbageCollectorMXBean 인스턴스의 개수 합계(마지막으로 보고된 이후 차이)입니다. GarbageCollectorMXBean.getCollectionCount()를 참조하세요. 예
GC Total Time 사용자 지정 메트릭 모든 GarbageCollectorMXBean 인스턴스의 시간 합계(마지막으로 보고된 이후 차이)입니다. GarbageCollectorMXBean.getCollectionTime()을 참조하세요. 예
Heap Memory Used (MB) 사용자 지정 메트릭 MemoryMXBean.getHeapMemoryUsage().getUsed()를 참조하세요. 예
% Of Max Heap Memory Used 사용자 지정 메트릭 java.lang:type=Memory / 최대 메모리 양(바이트)입니다. MemoryUsage를 참조하세요. 예
\Processor(_Total)\% Processor Time 기본 메트릭 시스템 전체 CPU 부하 틱 카운터(사용자 및 시스템만)의 차이를 지정된 시간 간격의 논리 프로세서 수로 나눈 값입니다. 아니요
\Process(??APP_WIN32_PROC??)\% Processor Time 기본 메트릭 OperatingSystemMXBean.getProcessCpuTime()(마지막으로 보고된 이후의 차이, 시간 및 CPU 수에 따라 정규화됨)을 참조하세요. 아니요
\Process(??APP_WIN32_PROC??)\Private Bytes 기본 메트릭 MemoryMXBean.getHeapMemoryUsage() 및 MemoryMXBean.getNonHeapMemoryUsage()의 합계입니다. 아니요
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec 기본 메트릭 /proc/[pid]/io 프로세스에서 읽고 쓴 바이트 합계(마지막으로 보고된 이후의 diff)입니다. proc(5)를 참조하세요. 아니요
\Memory\Available Bytes 기본 메트릭 OperatingSystemMXBean.getFreePhysicalMemorySize()를 참조하세요. 아니요

자주 묻는 질문

로그 프로세서가 TelemetryClient.trackTrace()를 사용하여 로그 파일을 처리하지 않는 이유는 무엇인가요?

TelemetryClient.trackTrace()는 Application Insights 클래식 SDK 브리지의 일부이며 로그 프로세서는 새 OpenTelemetry 기반 계측에서만 작동합니다.