Telemetry API에 OTLP 로그 쓰기

이 문서에서는 Telemetry (OTLP) API(telemetry.googleapis.com)의 로깅 엔드포인트로 OTLP 로그를 직접 전송하는 방법과 수집된 로그 항목을 Cloud Logging에서 확인하는 방법을 보여줍니다.

시작하기 전에

이 섹션에서는 Telemetry API를 사용하기 위한 환경을 설정하는 방법을 설명합니다.

Google Cloud 프로젝트 선택 또는 만들기

이 예시의 Google Cloud 프로젝트를 선택합니다. 아직 Google Cloud 프로젝트가 없으면 다음을 실행하여 만듭니다.

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

`gcloud` 설정

gcloud 도구는 Google Cloud CLI의 일부입니다. 설치에 대한 자세한 내용은 Google Cloud CLI 구성요소 관리를 참고하세요. 설치한 gcloud CLI 구성요소를 보려면 다음 명령어를 실행하세요.

gcloud components list

사용하도록 gcloud CLI를 구성하려면 PROJECT_ID 변수를Google Cloud 프로젝트의 식별자로 바꾼 후 다음 명령어를 실행하세요.

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

API 사용 설정

Google Cloud 프로젝트에서 Cloud Logging API와 Telemetry API를 사용 설정합니다. 원격 분석 API(telemetry.googleapis.com)에 특히 주의하세요. 이 문서에서 이 API를 처음 접했을 수도 있습니다.

다음 명령어의 출력에 API가 표시되면 이미 사용 설정된 것입니다.

gcloud services list

API 중 하나가 사용 설정되지 않은 경우 해당 명령어를 실행합니다.

gcloud services enable logging.googleapis.com
gcloud services enable telemetry.googleapis.com

로그 작성 권한 얻기

원격 분석 API에 로그를 쓰고 생성된 로그 항목을 보는 데 필요한 권한을 얻으려면 관리자에게 주 구성원에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.

로그 뷰어(roles/logging.viewer)
로그 작성자(roles/logging.logWriter)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Telemetry API를 사용하여 OTLP 로그 작성

이 섹션에서는 curl 유틸리티를 사용하여 OTLP 형식 로그 레코드를 만들고 텔레메트리 API로 레코드를 전송하는 방법을 설명합니다.

OTLP 로그 만들기

OTLP 형식의 로그 레코드가 포함된 JSON 파일을 만듭니다. 다음 탭에는 매우 간단한 로그 레코드와 더 복잡한 다중 로그 레코드가 포함되어 있습니다. 둘 중 하나를 선택하거나 각 메시지를 연속으로 보낼 수 있습니다.

간단한 OTLP 로그

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
          {"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
          {"key": "zone", "value": {"stringValue": "us-central1"}},
          {"key": "instance_id", "value": {"stringValue": "12345"}},
        ]
      },
      "scopeLogs": [
      {
        "logRecords": [
          { "eventName": "otlp-test-log",
            "body": { "stringValue": "This is a trivial log message." },
          }
        ]
      }
      ]
    }
  ]
}

더 복잡한 OTLP 로그

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
          {"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
          {"key": "zone", "value": {"stringValue": "us-central1"}},
          {"key": "instance_id", "value": {"stringValue": "12345"}},
        ]
      },
      "scopeLogs": [
      {
        "logRecords": [
          { "eventName": "otlp-test-log",
            "severityText": "INFO",
            "body": { "stringValue": "This is an informational message." },
            "attributes": [
              {"key": "string.attribute",
               "value": { "stringValue": "Here's some general info."}},
              {"key": "int.attribute",
               "value": { "intValue": "666"}},
              {"key": "double.attribute",
               "value": { "doubleValue": "3.14159"}},
              {"key": "boolean.attribute",
               "value": { "boolValue": true}},
            ]
          },
          { "eventName": "otlp-test-log",
            "severityText": "DEBUG",
            "body": { "stringValue": "This is a debug message." },
            "attributes": [
              {"key": "string.attribute",
               "value": { "stringValue": "Here's some debug info."}},
              {"key": "int.attribute",
               "value": { "intValue": "42"}},
              {"key": "double.attribute",
               "value": { "doubleValue": "6373.392"}},
              {"key": "boolean.attribute",
               "value": { "boolValue": false}},
             ]
          }
        ]
      }
      ]
    }
  ]
}

탭의 JSON 콘텐츠를 파일에 복사하고 파일을 저장합니다.

이 두 JSON 예시 모두 gce_instance 모니터링 리소스 유형에 대해 작성된 Cloud Logging 로그 항목을 생성합니다. scopedLogs 배열의 각 logRecord 항목은 OTLP 로그 레코드의 eventName 필드 값으로 이름이 지정된 로그에서 별도의 Cloud Logging 로그 항목이 됩니다. OTLP 로그가 Logging 로그 항목에 매핑되는 방식에 대한 자세한 내용은 다음을 참고하세요.

Telemetry API에 로그 전송

OTLP_LOG_JSON_FILE 변수를 생성한 파일의 이름으로 바꾼 후 다음 curl 명령어를 사용하여 파일의 콘텐츠를 원격 분석 API의 로깅 엔드포인트 https://telemetry.googleapis.com/v1/logs에 게시합니다.

curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJECT_ID}" \
-d @OTLP_LOG_JSON_FILE \
"https://telemetry.googleapis.com/v1/logs"

JSON 로그 레코드가 포함된 파일을 여러 개 만드는 경우 curl 명령어에서 OTLP_LOG_JSON_FILE 변수를 변경해야 합니다.

curl 명령어는 메시지 시퀀스를 생성하며, 성공하면 빈 응답 ({})을 생성합니다. 출력은 다음과 비슷합니다.

HTTP/2 200
x-google-esf-cloud-client-params: backend_service_name: "telemetry.googleapis.com" backend_fully_qualified_method: "opentelemetry.proto.collector.logs.v1.LogsService.Export"
[...]
x-google-gfe-response-code-details-trace: response_code_set_by_backend
x-google-gfe-response-body-transformations: gunzipped,chunked
x-google-shellfish-status: CA0gBEBG
x-google-gfe-version: 2.970.1
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
accept-ranges: none

{}

수집된 OTLP 로그 보기

로그 탐색기 및 관측 가능성 분석을 비롯한 Cloud Logging 도구를 사용하여 OTLP 로그로 인해 생성된 로그 항목을 볼 수 있습니다. 다음 섹션에서는 다음을 사용하여 로그 항목을 보는 방법을 설명합니다.

gcloud CLI
로그 탐색기

`gcloud`를 사용하여 로그 보기

gcloud logging read 명령어를 사용하여 방금 만든 로그 항목을 가져올 수 있습니다. 다음 명령어는 지난 5분 동안 작성된 otlp-test-log 로그의 로그 항목으로 출력을 제한합니다.

gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json

샘플 OTLP 로그에 해당하는 로그 항목은 다음과 같습니다.

간단한 로그 항목

[
  {
    "insertId": "1yt9bu7a0",
    "logName": "projects/PROJECT_ID/logs/otlp-test-log",
    "otel": {
      "resource": {
        "attributes": {
          "cloud.platform": "gcp_compute_engine",
          "gcp.project_id": "PROJECT_ID",
          "instance_id": "12345",
          "zone": "us-central1"
        }
      }
    },
    "receiveTimestamp": "2026-03-18T20:17:00.128801819Z",
    "resource": {
      "labels": {
        "instance_id": "12345",
        "project_id": "PROJECT_ID",
        "zone": "us-central1"
      },
      "type": "gce_instance"
    },
    "textPayload": "This is a trivial log message.",
    "timestamp": "2026-03-18T20:17:00.128801819Z"
  }
]

더 복잡한 로그 항목

[
  {
    "insertId": "1aw7fsja1",
    "labels": {
      "boolean.attribute": "false",
      "double.attribute": "6373.39",
      "int.attribute": "42",
      "string.attribute": "Here's some debug info."
    },
    "logName": "projects/PROJECT_ID/logs/otlp-test-log",
    "otel": {
      "resource": {
        "attributes": {
          "cloud.platform": "gcp_compute_engine",
          "gcp.project_id": "PROJECT_ID",
          "instance_id": "12345",
          "zone": "us-central1"
        }
      }
    },
    "receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
    "resource": {
      "labels": {
        "instance_id": "12345",
        "project_id": "PROJECT_ID",
        "zone": "us-central1"
      },
      "type": "gce_instance"
    },
    "severity": "DEBUG",
    "textPayload": "This is a debug message.",
    "timestamp": "2026-03-16T17:11:19.461096569Z"
  },
  {
    "insertId": "1aw7fsja0",
    "labels": {
      "boolean.attribute": "true",
      "double.attribute": "3.14159",
      "int.attribute": "666",
      "string.attribute": "Here's some general info."
    },
    "logName": "projects/PROJECT_ID/logs/otlp-test-log",
    "otel": {
      "resource": {
        "attributes": {
          "cloud.platform": "gcp_compute_engine",
          "gcp.project_id": "PROJECT_ID",
          "instance_id": "12345",
          "zone": "us-central1"
        }
      }
    },
    "receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
    "resource": {
      "labels": {
        "instance_id": "12345",
        "project_id": "PROJECT_ID",
        "zone": "us-central1"
      },
      "type": "gce_instance"
    },
    "severity": "INFO",
    "textPayload": "This is an informational message.",
    "timestamp": "2026-03-16T17:11:19.461096569Z"
  }
]

로그 탐색기를 사용하여 로그 보기

Google Cloud 콘솔에서 OTLP 로그로 생성된 로그 항목을 보려면 다음을 수행하세요.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
로그 탐색기로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
OTLP 로그를 전송한 Google Cloud 프로젝트를 선택합니다.
쿼리 창을 사용하여 쿼리를 입력합니다. 이 문서의 샘플은 otlp-test-log이라는 로그에 작성됩니다. 이 로그에서 항목을 검색하려면 다음 쿼리를 입력합니다.
```
LOG_ID(otlp-test-log)
```
쿼리 실행을 클릭합니다.

삭제

새 프로젝트를 만들었지만 더 이상 필요하지 않은 경우 프로젝트를 삭제하면 Google Cloud 계정에 요금이 청구되지 않습니다.

다음 단계

Telemetry API에 대해 자세히 알아보려면 다음 문서를 참고하세요.

API 개요에서는 로그, 측정항목, 트레이스를 위한 Telemetry API를 설명합니다.
v1.logs는 로깅을 위한 Telemetry API 엔드포인트를 설명하고 OTLP 로그 레코드가 Cloud Logging 로그 항목으로 수집되는 방법에 관한 자세한 정보를 제공합니다.