이 문서에서는 클라이언트 라이브러리 또는 Logging 에이전트를 사용하여 애플리케이션 로그를 Cloud Logging으로 프로그래매틱 방식으로 전송할지 여부를 결정하는 데 필요한 정보를 제공합니다. Logging 에이전트는 stdout 또는 파일에 작성된 데이터를 Cloud Logging에 로그로 전송합니다. Google Kubernetes Engine, App Engine 가변형 환경, Cloud Run 함수와 같은 서비스에는 통합 Logging 에이전트가 포함되어 있습니다. Compute Engine의 경우 운영 에이전트 또는 기존 Cloud Logging 에이전트를 설치할 수 있습니다.
이러한 에이전트는 알려진 파일 위치 또는 Windows Event Log, journald, syslogd 등의 로깅 서비스에서 로그를 수집합니다.
클라이언트 라이브러리나 Logging 에이전트를 사용할 수 없거나 실험만 원하는 경우 gcloud logging write 명령어를 사용하거나 Cloud Logging API 엔드포인트 entries.write에 HTTP 명령어를 전송하여 로그를 작성할 수 있습니다.
Cloud Logging API는 HTTP 및 gRPC 호출을 모두 지원합니다. 운영 에이전트와 대부분의 Logging 클라이언트 라이브러리는 gRPC Logging API를 호출합니다. 일부 언어의 기존 Logging 에이전트와 클라이언트 라이브러리는 REST Logging API를 호출합니다.
에이전트 또는 클라이언트 라이브러리 선택
에이전트 또는 클라이언트 라이브러리를 결정할 때는 다음 질문을 고려하세요.
애플리케이션이 Google Cloud외부에서 실행되고 있나요?
애플리케이션이 Google Cloud에서 실행되고 있지 않으면 로그를 Logging API로 전송하는 방법이 필요합니다. 로그를 온프레미스 시스템에서 Logging으로 라우팅하려면 OpenTelemetry 수집기를 배포하고 관리하여 원격 분석을 Google Cloud로 전송하는 Bindplane을 사용하는 것이 좋습니다. 자세한 내용은 Bindplane 정보를 참조하세요.
또는 클라이언트 라이브러리를 사용하여 애플리케이션에서 직접 로그를 Logging으로 라우팅할 수 있습니다. 서버리스 컴퓨팅과 같은 임시 환경의 경우 클라이언트 라이브러리를 사용하여 Logging API를 직접 호출해야 합니다.
애플리케이션을 실행하는 Google Cloud 서비스에서
stdout 및 stderr 콘텐츠를 프로젝트에 작성할 수 있나요?
일부 Google Cloud 서비스는 완전 관리형이므로 에이전트를 사용하여 로그를 Google Cloud 프로젝트에 전송할 필요가 없습니다. 원하는 언어(예: Go, Node.js, Python)로 설정된 로깅 프레임워크를 사용하여 기본적으로 stdout 및 stderr가 지원되는 제품에서 로그를 Logging으로 전송할 수 있습니다. 클라이언트 라이브러리를 사용하는 대신 stdout 및 stderr를 사용하는 이점은 애플리케이션 비정상 종료로 인해 로그를 프로젝트에 전송이 중단되지 않는다는 점입니다. stdout 및 stderr를 통해 구조화된 로그를 전송하는 방법에 대한 자세한 내용은 애플리케이션에서 로그 형식을 유연하게 변경할 수 있나요? 섹션을 참조하세요.
Logging 클라이언트 라이브러리를 사용할 수 있지만 반드시 필요하지 않으면 로컬 테스트를 위해 Logging에 종속 항목을 도입할 수 있습니다. 클라이언트 라이브러리를 사용하려면 버퍼링과 재시도를 명시적으로 처리하는 더 복잡한 코딩이 필요할 수도 있습니다.
또한 Logging 클라이언트 라이브러리를 사용할 때마다 API에 대한 새 연결 스트림이 생성됩니다. 이러한 새 연결은 더욱 복잡하고 추가 포트를 사용하며 애플리케이션의 로그만 있는 별도의 요청을 전송하므로 로그가 많지 않으면 낭비될 수 있습니다.
로컬 환경에서 애플리케이션 로그에 액세스할 수 있어야 하나요?
디버깅 및 기타 목적으로 로컬 환경에서 애플리케이션 로그에 액세스해야 하는 경우 일부 언어의 로깅 모듈을 사용하여 stdout 및 stderr로 출력할 수 있습니다. 일부 언어의 Logging 클라이언트 라이브러리에서는 로그를 stdout 및 stderr로 라우팅할 수 있습니다.
stdout 및 stderr로 작성된 로그를 자동으로Google Cloud 프로젝트에 전송할 수 없는 Google Cloud 에서 애플리케이션을 실행하면 온디스크 파일에서 stdout 및 stderr 로그를 수집하고 에이전트에서 해당 로그를 스크래핑하도록 구성한 후 Logging에 전송할 수 있습니다. 자세한 내용은 운영 에이전트 또는 기존 Logging 에이전트의 구성 가이드를 참조하세요.
에이전트 설치 프로세스는 수동인가요, 아니면 자동인가요?
일부 서비스는 에이전트를 자동으로 설치하거나 개발자가 직접 에이전트를 설치하도록 허용합니다. 사용 중인 서비스에서 에이전트 설치를 허용하지 않는 경우에는 클라이언트 라이브러리를 사용하여 Logging을 사용해야 합니다.
이 질문은 애플리케이션에서 구조화된 로그를 생성할 수 있는지를 판단하는 데 도움이 됩니다.
로그를 구조화된 로깅 형식으로 Logging API로 전송하면 Logging에서 구조화된 로그를 인식합니다.
클라이언트 라이브러리는 이 형식을 처리할 수 있는 메서드를 제공합니다.
구조화된 로그를 인식하도록 에이전트를 구성해야 합니다.
기본적으로 에이전트는 JSON 형식의 로그를 감지하고 구조화된 로그로 처리되도록 구성됩니다. 애플리케이션에 개발자가 변경할 수 없는 자체 로그 형식이 있지만 로그가 구조화된 로그로 인식되게 하려면 에이전트가 로그를 구조화된 로그로 인식할 수 있도록 로그를 구조화된 로깅 형식(일반적으로 JSON)으로 stdout 및 stderr에 작성해야 합니다. 그렇지 않으면 에이전트가 자체 형식을 이해하도록 구성해야 합니다.
각 옵션 요약
Cloud Logging 클라이언트 라이브러리
장점
로그를 직접 Cloud Logging API로 라우팅할 수 있습니다.
일부 언어는 라이브러리를 사용하여 로그를 stdout 및 stderr로 출력할 수 있습니다.
단점
애플리케이션 비정상 종료로 인해 로그가 Google Cloud 프로젝트에 전송되지 않습니다.
운영 에이전트
장점
운영 에이전트는 안정적인 오픈소스 기술(로그 수집용 Fluent Bit, 측정항목 수집용 OpenTelemetry Collector)을 사용하여 로그와 측정항목을 전송할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-04-23(UTC)"],[],[],null,["# Which should you use: Logging agent or client library?\n\nThis document provides the information that you need to help you decide whether\nto programmatically send application logs to Cloud Logging by using\n[client libraries](/logging/docs/reference/libraries) or by using a\nlogging agent. Logging agents send data written to a file, such as\n`stdout` or a file, as logs to Cloud Logging. Services such as\nGoogle Kubernetes Engine, App Engine flexible environment, and Cloud Run functions, contain an integrated\nlogging agent. For Compute Engine, you can install the\n[Ops Agent or the legacy Cloud Logging agent](/logging/docs/agent).\nThese agents collect logs from known file locations or logging\nservices like the `Windows Event Log`, `journald`, or `syslogd`.\n\nWhen you can't use a client library or a Logging agent, or when\nyou only want to experiment, you can write logs by using the\n[`gcloud logging write`](/sdk/gcloud/reference/logging/write)\ncommand or by sending HTTP commands to the Cloud Logging API endpoint\n[`entries.write`](/logging/docs/reference/v2/rest/v2/entries/write).\nThe [Cloud Logging API](/logging/docs/reference/api-overview) supports both\nHTTP and gRPC calls. The Ops Agent and most Logging client\nlibraries call the gRPC Logging API. The legacy Logging\nagent and client libraries for some languages call the REST\nLogging API.\n| **Note:** There will be no new feature development or support for new operating systems for the legacy Logging agent. We recommend that you use the [Ops Agent](/logging/docs/agent/ops-agent) for new workloads and eventually transition your existing VMs to use the Ops Agent.\n\nChoosing an agent or client libraries\n-------------------------------------\n\nWhen you're deciding between an agent or the client libraries, consider\nthe following questions:\n\nIs your application running outside of Google Cloud?\n\n: If your application isn't running on Google Cloud, you need\n some way to send logs to the Logging API. To route logs from\n on-premises systems to Logging, we recommend that you use\n [Bindplane](https://bindplane.com/google), which deploys and manages\n OpenTelemetry collectors to send telemetry to Google Cloud. For more\n information, see [About Bindplane](/stackdriver/bindplane).\n\n Alternatively, you can route logs to Logging directly from\n the application by using client libraries. For ephemeral environments,\n like Serverless computing, you must use client libraries to make direct\n calls to the Logging API.\n\nDoes the Google Cloud service running your application support\nwriting `stdout` and `stderr` content to your project?\n\n: Some Google Cloud services are fully managed, so you don't need\n to use agents to send logs to your Google Cloud project. You can use any\n established logging framework in\n the language of your choice, such as Go, Node.js, and Python, to send logs to\n Logging in products where `stdout` and `stderr` are supported\n by default. An advantage to relying on `stdout` and `stderr`\n instead of using client libraries is that application crashes don't break\n sending logs to your project. For information about sending\n [structured logs](/logging/docs/structured-logging) through `stdout` and\n `stderr`, see the section, [Does your application have the flexibility to\n change the log format?](#log-format).\n\n You can use Logging client libraries, but keep in mind that\n it might introduce a dependency on Logging for local testing,\n when you don't necessarily need it. Using the client libraries might also\n require more complex coding to explicitly handle buffering and retries.\n Also, each use of the Logging client libraries creates a new\n connection stream to the API. These new connections introduce more\n complexity, use additional ports, and send separate requests with only the\n logs from the application, which could be wasteful if there aren't many\n logs.\n\nDo the application logs need to be accessible in your local environment?\n\n: If you need to access the application logs in your local environment, for\n debugging and other purposes, then you can use the logging modules in some\n languages to output to `stdout` and `stderr`. Logging client\n libraries for some languages support routing logs to `stdout` and `stderr`.\n\n When running your application in Google Cloud services that don't support\n automatically sending logs written to `stdout` and `stderr` to your\n Google Cloud project, you can collect\n `stdout` and `stderr` logs in on-disk files and configure the agent to\n scrape those and send them to Logging. For more information,\n see the configuration guide for the [Ops Agent](/logging/docs/agent/ops-agent/configuration)\n or the legacy [Logging agent](/logging/docs/agent/logging/configuration).\n\nIs the agent-installation process manual or automatic?\n\n: Some services install agents automatically or allow you to install the agents\n yourself. If the service you are using doesn't allow you to install agents,\n then you must use the client libraries to use Logging.\n\nAre you running Fluentd in your system already?\n\n: The legacy Logging agent is based on Fluentd.\n\n If you already have Fluentd running in your system, and you would like to\n use that daemon to send your logs to Logging, then use the\n [Google Cloud Logging plugin for\n fluentd](https://github.com/GoogleCloudPlatform/fluent-plugin-google-cloud).\n\nAre you collecting application metrics for Cloud Monitoring as well?\n\n: In Compute Engine VMs, the Ops Agent can collect logs and most metrics. See\n [Ops Agent features](/stackdriver/docs/solutions/agents/ops-agent#features) for more information.\n\n If the Ops Agent doesn't address your use cases, then you can use the\n [legacy Monitoring agent](/monitoring/agent/monitoring) or the\n [Monitoring client libraries](/monitoring/docs/reference/libraries)\n to collect your metrics.\n\nDoes your application have the flexibility to change the log format?\n\n: This question helps you decide if your application can generate\n [structured logs](/logging/docs/structured-logging).\n Logging recognizes structured logs if you send the logs to the\n Logging API in [the structured-logging format](/logging/docs/reference/v2/rpc/google.logging.v2#google.logging.v2.WriteLogEntriesRequest).\n Client libraries provide the methods for handling this format.\n\n There are two way of writing structured logs: one is to set [specific fields\n in the `LogEntry` envelope](/logging/docs/structured-logging#special-payload-fields),\n and the other is to set the [`jsonPayload` field within the `LogEntry`\n envelope](/logging/docs/structured-logging#use-gcloud).\n The schema for the former is determined by Cloud Logging, while the\n schema for the latter is determined by the user.\n\n You must configure the agent to recognize [structured logs](/logging/docs/structured-logging).\n By default, the agents are configured to detect logs in JSON format and to\n handle them as structured logs. If your application has its own log format\n that you can't change, but you want the logs to be recognized as structured\n logs, then you must write logs in the structured-logging format, usually\n JSON, to `stdout` and `stderr`, so that the agents can recognize them as\n structured logs. Otherwise, you must configure your agent to understand your\n own format.\n\nSummary of each option\n----------------------\n\n- Cloud Logging client libraries\n\n - Advantages\n\n - You can route logs directly to Cloud Logging API.\n - Some languages can output logs to `stdout` and `stderr` by using the library.\n - Disadvantages\n\n - Application crashes break sending logs to your Google Cloud project.\n- Ops Agent\n\n - Advantages\n\n - The Ops Agent can send logs and metrics by using stable open source technologies: Fluent Bit for log collection and the OpenTelemetry Collector for metric collection.\n - You can collect both logs and metrics from many common applications; see [Monitor and collect logs from third-party\n applications](/stackdriver/docs/solutions/agents/ops-agent/third-party).\n - You can retain logs in your local environment.\n - You might be able to recover logs from application crashes.\n - The Ops Agent is under active development.\n - Disadvantages\n\n - Fluent Bit only supports UTF-8 encoding. It doesn't support encoding conversion.\n- Legacy Logging agent\n\n - Advantages\n - The agent uses Fluentd to collect logs, which supports encoding conversion.\n - You can retain logs in your local environment.\n - You might be able to recover logs from application crashes.\n - Disadvantages\n - The agent is currently supported but is not under active development.\n- `stdout` and `stderr` logs automatically sent to your Google Cloud project\n\n - Advantages\n - This process is a common way to emit logs to local environments.\n - You can use arbitrary logging libraries.\n - You might be able to recover logs from application crashes.\n - Disadvantages\n - Not all environments automatically route logs to Logging."]]
