# Lambda 확장을 사용하여 Lambda 함수 보강
Lambda 익스텐션을 사용하여 Lambda 함수를 보강할 수 있습니다. 예를 들어 Lambda 익스텐션을 사용하여 원하는 모니터링, 관찰, 보안 및 거버넌스 도구와 함수를 통합할 수 있습니다. [AWS Lambda 파트너](https://aws.amazon.com/lambda/partners/)가 제공하는 다양한 도구 중에서 선택하거나 [자체적인 Lambda 익스텐션을 만들 수 있습니다](runtimes-extensions-api.md).
Lambda는 외부 및 내부 익스텐션을 지원합니다. 외부 익스텐션은 실행 환경에서 독립 프로세스로 실행되며 함수 호출이 완전히 처리된 후에도 계속 실행됩니다. 익스텐션은 별도의 프로세스로 실행되므로 함수와 다른 언어로 작성할 수 있습니다. 모든 [Lambda 런타임](lambda-runtimes.md)은 익스텐션을 지원합니다.
내부 익스텐션은 런타임 프로세스의 일부로 실행됩니다. 함수는 래퍼 스크립트 또는 `JAVA_TOOL_OPTIONS`와 같은 프로세스 내 메커니즘을 사용하여 내부 익스텐션에 액세스합니다. 자세한 내용은 [런타임 환경 수정](runtimes-modify.md) 섹션을 참조하세요.
Lambda 콘솔, AWS Command Line Interface(AWS CLI) 또는 CloudFormation, AWS Serverless Application Model (AWS SAM), Terraform과 같은 IaC(Infrastructure as code) 서비스 및 도구를 사용하여 함수에 익스텐션을 추가할 수 있습니다.
익스텐션에서 소비한 실행 시간(1밀리초 단위)에 대해 요금이 청구됩니다. 자체 익스텐션을 설치하는 데는 비용이 들지 않습니다. 익스텐션의 요금에 대한 자세한 내용은 [AWS Lambda 요금](https://aws.amazon.com/lambda/pricing/)을 참조하십시오. 파트너 익스텐션에 대한 요금 정보는 해당 파트너의 웹 사이트를 참조하십시오. 공식 파트너 확장 프로그램 목록은 [AWS Lambda 확장 파트너](extensions-api-partners.md) 섹션을 참조하세요.
**Topics**
+ [
## 실행 환경
](#using-extensions-env)
+ [
## 성능 및 리소스에 미치는 영향
](#using-extensions-reg)
+ [
## 권한
](#using-extensions-permissions)
+ [
# Lambda 확장 구성
](extensions-configuration.md)
+ [
# AWS Lambda 확장 파트너
](extensions-api-partners.md)
+ [
# Lambda 확장 API를 사용하여 확장 생성
](runtimes-extensions-api.md)
+ [
# 텔레메트리 API를 사용하여 확장의 실시간 텔레메트리 데이터에 액세스
](telemetry-api.md)
## 실행 환경
Lambda는 안전하고 격리된 런타임 환경을 제공하는 [실행 환경](lambda-runtime-environment.md)에서 함수를 간접 호출합니다. 실행 환경은 함수를 실행하는 데 필요한 리소스를 관리하고 함수의 런타임 및 익스텐션에 대한 수명 주기 지원을 제공합니다.
실행 환경의 수명 주기에는 다음 단계가 포함됩니다.
+ `Init`: 이 단계 중에 Lambda는 구성된 리소스로 실행 환경을 만들거나 고정 해제하고, 함수와 모든 계층의 코드를 다운로드하고, 모든 익스텐션을 초기화하고, 런타임을 초기화한 다음 함수의 초기화 코드(기본 핸들러 외부의 코드)를 실행합니다. `Init` 단계는 첫 번째 호출 중에 발생하거나, [프로비저닝된 동시성](provisioned-concurrency.md)을 사용하도록 설정한 경우 함수 호출 전에 발생합니다.
`Init` 단계는 세 가지 하위 단계(`Extension init`, `Runtime init`, `Function init`.)로 나뉩니다. 이러한 하위 단계는 함수 코드가 실행되기 전에 모든 익스텐션과 런타임이 자신의 설정 작업을 완료하도록 보장합니다.
[Lambda SnapStart](snapstart.md)가 활성화되면 함수 버전을 게시할 때 `Init` 단계가 발생합니다. Lambda는 초기화된 실행 환경의 메모리 및 디스크 상태 스냅샷을 저장하고 암호화된 스냅샷을 유지하며 짧은 지연 시간으로 액세스할 수 있도록 스냅샷을 캐싱합니다. 체크포인트 이전의 [런타임 후크](snapstart-runtime-hooks.md)가 있는 경우 코드는 `Init` 단계가 끝날 때 실행됩니다.
+ `Restore`(SnapStart만 해당): [SnapStart](snapstart.md) 함수를 처음 간접 호출하고 함수가 스케일 업되면 Lambda는 이 함수를 처음부터 초기화하는 대신 유지된 스냅샷에서 새 실행 환경을 재개합니다. 복원 후 [런타임 후크](snapstart-runtime-hooks.md)가 있는 경우 코드는 `Restore` 단계가 끝날 때 실행됩니다. 복원 후 런타임 후크 지속 시간에 대해 요금이 청구됩니다. 런타임이 로드되고 복원 후 런타임 후크가 제한 시간(10초) 내에 완료되어야 합니다. 그렇지 않으면 SnapStartTimeoutException이 발생합니다. `Restore` 단계가 완료되면 Lambda가 함수 핸들러([간접 호출 단계](lambda-runtime-environment.md#runtimes-lifecycle-invoke))를 간접적으로 간접 호출합니다.
+ `Invoke`: 이 단계에서 Lambda는 함수 핸들러를 간접 호출합니다. 함수의 실행이 완료한 후 Lambda는 다른 함수 호출을 처리할 준비를 합니다.
+ `Shutdown`: Lambda 함수가 일정 기간 동안 호출을 받지 않으면 이 단계가 트리거됩니다. `Shutdown` 단계에서 Lambda는 런타임을 종료하고 익스텐션이 완전히 중지되도록 알림을 보낸 다음 환경을 제거합니다. Lambda는 각 익스텐션에 `Shutdown` 이벤트를 보냅니다. 이 이벤트는 환경이 곧 종료됨을 익스텐션에 알립니다.
`Init` 단계 중에 Lambda는 익스텐션을 포함한 계층을 실행 환경의 `/opt` 디렉터리로 추출합니다. Lambda는 `/opt/extensions/` 디렉터리에서 익스텐션을 찾고, 익스텐션을 실행하기 위해 각 파일을 실행 가능한 부트스트랩으로 해석하고, 모든 익스텐션을 병행하여 시작합니다.
## 성능 및 리소스에 미치는 영향
함수의 익스텐션 크기는 배포 패키지 크기 제한에 포함됩니다. .zip 파일 아카이브의 경우 함수 및 모든 익스텐션의 압축 해제된 총 크기는 압축 해제된 배포 패키지 크기 제한인 250MB를 초과할 수 없습니다.
익스텐션은 CPU, 메모리, 스토리지와 같은 함수 리소스를 공유하므로 함수의 성능에 영향을 줄 수 있습니다. 예를 들어 익스텐션이 컴퓨팅 집약적 작업을 수행하는 경우 함수의 실행 시간이 늘어날 수 있습니다.
각 익스텐션은 Lambda가 함수를 간접 호출하기 전에 초기화를 완료해야 합니다. 따라서 상당한 초기화 시간을 소비하는 익스텐션은 함수 호출의 지연 시간을 증가시킬 수 있습니다.
함수 실행 후 익스텐션에 소요되는 추가 시간을 측정하려면 `PostRuntimeExtensionsDuration` [함수 지표](monitoring-metrics.md)를 사용하고, 사용된 메모리 증가를 측정하려면 `MaxMemoryUsed` 지표를 사용합니다. 특정 익스텐션의 영향을 파악하려는 경우 서로 다른 버전의 함수를 나란히 실행하면 됩니다.
**참고**
`MaxMemoryUsed` 지표는 [Lambda Insights에서 수집하는 지표](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics.html) 중 하나이며 Lambda 기본 지표가 아닙니다.
## 권한
익스텐션은 함수와 동일한 리소스에 액세스할 수 있습니다. 익스텐션은 함수와 동일한 환경 내에서 실행되므로 함수와 익스텐션 간에 권한이 공유됩니다.
.zip 파일 아카이브의 경우 CloudFormation 템플릿을 생성하여 AWS Identity and Access Management(IAM) 권한을 포함한 동일한 익스텐션 구성을 여러 함수에 연결하는 작업을 간소화할 수 있습니다.
# Lambda 확장 구성
## 익스텐션 구성(.zip 파일 아카이브)
익스텐션을 함수에 [Lambda 계층](chapter-layers.md)으로 추가할 수 있습니다. 계층을 사용하면 조직 내에서 또는 전체 Lambda 개발자 커뮤니티에서 익스텐션 프로그램을 공유할 수 있습니다. 계층에 하나 이상의 익스텐션을 추가할 수 있습니다. 각 함수에 최대 10개의 익스텐션을 등록할 수 있습니다.
계층에 대해 사용하는 것과 동일한 방법으로 함수에 익스텐션을 추가합니다. 자세한 내용은 [계층으로 Lambda 종속성 관리](chapter-layers.md) 단원을 참조하십시오.
**함수에 익스텐션 프로그램 추가(콘솔)**
1. Lambda 콘솔의 [함수 페이지](https://console.aws.amazon.com/lambda/home#/functions)를 엽니다.
1. 함수를 선택합니다.
1. 아직 선택되지 않은 경우 **코드(Code)** 탭을 선택합니다.
1. **계층(Layers)**에서 **편집(Edit)**을 선택합니다.
1. **계층 선택(Choose a layer)**에서 **ARN 지정(Specify an ARN)**을 선택합니다.
1. **ARN 지정(Specify an ARN)**에서 익스텐션 계층의 Amazon 리소스 이름(ARN)을 입력합니다.
1. **추가**를 선택합니다.
## 컨테이너 이미지에서 익스텐션 사용
[컨테이너 이미지](images-create.md)에 익스텐션을 추가할 수 있습니다. ENTRYPOINT 컨테이너 이미지 설정은 함수의 주 프로세스를 지정합니다. Dockerfile에서 ENTRYPOINT 설정을 구성하거나 함수 구성에서 재정의로 구성합니다.
컨테이너 내에서 여러 프로세스를 실행할 수 있습니다. Lambda는 주 프로세스와 모든 추가 프로세스의 수명 주기를 관리합니다. Lambda는 [익스텐션 API](runtimes-extensions-api.md)를 사용하여 익스텐션 수명 주기를 관리합니다.
### 예: 외부 익스텐션 추가
외부 익스텐션은 Lambda 함수와 별도의 프로세스에서 실행됩니다. Lambda는 `/opt/extensions/` 디렉터리의 각 익스텐션에 대해 프로세스를 시작합니다. Lambda는 익스텐션 API를 사용하여 익스텐션 수명 주기를 관리합니다. 함수가 완료될 때까지 실행된 후 Lambda는 각 외부 익스텐션에 `Shutdown` 이벤트를 보냅니다.
**Example Python 기본 이미지에 외부 익스텐션 추가**
```
FROM public.ecr.aws/lambda/python:3.11
# Copy and install the app
COPY /app /app
WORKDIR /app
RUN pip install -r requirements.txt
# Add an extension from the local directory into /opt/extensions
ADD my-extension.zip /opt/extensions
CMD python ./my-function.py
```
## 다음 단계
익스텐션에 대해 자세히 알아보려면 다음 리소스를 사용하는 것이 좋습니다.
+ 기본적인 작업 예는 AWS Lambda 컴퓨팅 블로그에서 [AWS용 익스텐션 빌드](https://aws.amazon.com/blogs/compute/building-extensions-for-aws-lambda-in-preview/)를 참조하세요.
+ AWS Lambda 파트너가 제공하는 익스텐션에 대한 자세한 내용은 AWS Lambda 컴퓨팅 블로그에서 [AWS 익스텐션 소개](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-extensions-in-preview/)를 참조하세요.
+ 사용 가능한 예제 익스텐션 및 래퍼 스크립트를 보려면 AWS Lambda 샘플 GitHub 리포지토리에서 [AWS 익스텐션](https://github.com/aws-samples/aws-lambda-extensions)을 참조하세요.
# AWS Lambda 확장 파트너
AWS Lambda는 여러 서드 파티 엔터티와 협력하여 Lambda 함수와 통합할 확장을 제공합니다. 다음 목록에서는 언제든 사용할 수 있는 서드 파티 확장 프로그램에 대해 자세히 설명합니다.
+ [https://docs.appdynamics.com/display/PRO20X/Use+the+AppDynamics+AWS+Lambda+Extension+to+Instrument+Serverless+APM+at+Runtime](https://docs.appdynamics.com/display/PRO20X/Use+the+AppDynamics+AWS+Lambda+Extension+to+Instrument+Serverless+APM+at+Runtime) - Node.js 또는 Python Lambda 함수를 자동으로 계측하여 함수 성능에 대한 가시성 및 경고를 제공합니다.
+ [https://axiom.co/docs/apps/lambda](https://axiom.co/docs/apps/lambda) — Lambda 함수 성능을 모니터링하고 시스템 수준 지표를 집계하기 위한 대시보드를 제공합니다.
+ [https://docs.datadoghq.com/serverless/datadog_lambda_library/extension/](https://docs.datadoghq.com/serverless/datadog_lambda_library/extension/) - 메트릭, 추적 및 로그를 사용하여 서버리스 애플리케이션에 대한 종합적인 실시간 가시성을 제공합니다.
+ [https://www.dynatrace.com/support/help/technology-support/cloud-platforms/amazon-web-services/integrations/deploy-oneagent-as-lambda-extension/](https://www.dynatrace.com/support/help/technology-support/cloud-platforms/amazon-web-services/integrations/deploy-oneagent-as-lambda-extension/) - 추적 및 지표에 대한 가시성을 제공하고 AI를 활용하여 전체 애플리케이션 스택에서 자동화된 오류 감지 및 근본 원인 분석을 수행합니다.
+ [https://www.elastic.co/guide/en/apm/agent/nodejs/current/lambda.html](https://www.elastic.co/guide/en/apm/agent/nodejs/current/lambda.html) - 상관 관계가 있는 추적, 지표 및 로그를 사용하여 근본 원인 문제를 식별하고 해결하는 애플리케이션 성능 모니터링(APM)을 제공합니다.
+ [https://docs.epsagon.com/docs/environment-monitoring/lambda/intro](https://docs.epsagon.com/docs/environment-monitoring/lambda/intro) - 호출 이벤트를 수신하고 추적을 저장한 다음, Lambda 함수 실행에 병렬로 전송합니다.
+ [https://docs.fastly.com/signalsciences/install-guides/paas/aws-lambda/](https://docs.fastly.com/signalsciences/install-guides/paas/aws-lambda/) - 인젝션 방식 공격, 자격 증명 스터핑을 통한 계정 탈취, 악성 봇, API 남용과 같은 의심스러운 활동으로부터 Lambda 함수를 보호합니다.
+ [https://learn.hashicorp.com/tutorials/vault/aws-lambda](https://learn.hashicorp.com/tutorials/vault/aws-lambda) - 비밀 정보를 관리하고 개발자가 Vault가 인식하는 기능을 만들지 않고도 함수 코드 내에서 사용할 수 있도록 합니다.
+ [https://docs.honeycomb.io/getting-data-in/integrations/aws/aws-lambda/](https://docs.honeycomb.io/getting-data-in/integrations/aws/aws-lambda/) - 앱 스택 디버깅을 위한 가시성 도구입니다.
+ [https://docs.lumigo.io/docs/lambda-extensions](https://docs.lumigo.io/docs/lambda-extensions) - Lambda 함수 호출을 프로파일링하고 지표를 수집하여 서버리스 및 마이크로서비스 환경에서 문제를 해결합니다.
+ [https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/get-started/monitoring-aws-lambda-serverless-monitoring](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/get-started/monitoring-aws-lambda-serverless-monitoring) - Lambda 함수와 함께 실행하여 원격 분석 정보를 자동으로 수집 및 향상하고 New Relic의 통합 가시성 플랫폼으로 전송합니다.
+ [https://docs.sedai.io/get-started/platform/optimization/aws/lambda](https://docs.sedai.io/get-started/platform/optimization/aws/lambda) - AI/ML을 기반으로 하는 자율 운영 관리 플랫폼으로, 클라우드 운영 팀이 클라우드 비용 절감, 성능 및 대규모 가용성을 극대화할 수 있도록 지속적인 최적화를 제공합니다.
+ [https://docs.sentry.io/platforms/javascript/guides/aws-lambda/](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/) - Lambda 함수의 성능을 진단, 수정 및 최적화합니다.
+ [https://www.site24x7.com/help/aws/lambda-execution-logs.html](https://www.site24x7.com/help/aws/lambda-execution-logs.html) - Lambda 환경에 대한 실시간 가시성을 달성합니다
+ [https://github.com/signalfx/splunk-otel-lambda](https://github.com/signalfx/splunk-otel-lambda) - Lambda 함수의 효율적이고 효과적인 모니터링을 위해 지연 시간이 짧은 고해상도 지표를 수집합니다.
+ [https://help.sumologic.com/03Send-Data/Collect-from-Other-Data-Sources/Collect_AWS_Lambda_Logs_using_an_Extension](https://help.sumologic.com/03Send-Data/Collect-from-Other-Data-Sources/Collect_AWS_Lambda_Logs_using_an_Extension) - 서버리스 애플리케이션의 상태 및 성능에 대한 가시성을 제공합니다.
+ [솔트 보안](https://salt.security/press-releases/salt-security-becomes-the-first-and-only-api-security-vendor-to-join-aws-lambda-ready-program?) - 다양한 런타임에 대한 자동 설정 및 지원을 통해 Lambda 함수의 API 상태 거버넌스와 API 보안을 간소화합니다.
## AWS 관리형 확장
AWS는 다음과 같은 자체 관리형 확장을 제공합니다.
+ [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions.html#appconfig-integration-lambda-extensions-enabling) - 기능 플래그와 동적 데이터를 사용하여 Lambda 함수를 업데이트합니다. 이 확장을 사용하여 운영 제한 및 튜닝과 같은 다른 동적 구성을 업데이트할 수도 있습니다.
+ [Amazon CodeGuru Profiler](https://docs.aws.amazon.com/codeguru/latest/profiler-ug/python-lambda-layers.html) - 애플리케이션에서 가장 비싼 코드 라인을 정확히 파악하고 코드 개선을 위한 권장 사항을 제공하여 애플리케이션 성능을 개선하고 비용을 절감합니다.
+ [CloudWatch Lambda Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights.html) - 자동화된 대시보드를 통해 Lambda 함수의 성능을 모니터링하고, 문제를 해결하고, 최적화합니다.
+ [AWS Distro for OpenTelemetry(ADOT)](https://aws.amazon.com/otel) - 함수를 활성화하여 AWS X-Ray 등의 AWS 모니터링 서비스와 Honeycomb 및 Lightstep 등의 OpenTelemetry 지원 대상에 추적 데이터를 전송합니다.
+ [AWS 파라미터 및 보안 암호](with-secrets-manager.md) - Lambda 함수에서 AWS Systems Manager Systems Manager Parameter Store의 파라미터와 AWS Secrets Manager의 보안 암호를 안전하게 검색합니다.
추가 확장 샘플 및 데모 프로젝트는 [AWS Lambda 확장](https://github.com/aws-samples/aws-lambda-extensions) 섹션을 참조하세요.
# Lambda 확장 API를 사용하여 확장 생성
Lambda 함수 작성자는 익스텐션을 사용하여 모니터링, 관찰, 보안 및 거버넌스를 위해 선호하는 도구와 Lambda를 통합합니다. 함수 작성자는 AWS, [AWS 파트너](extensions-api-partners.md) 및 오픈 소스 프로젝트의 익스텐션을 사용할 수 있습니다. 익스텐션 사용에 대한 자세한 내용은 AWS Lambda 컴퓨팅 블로그의 [AWS 익스텐션 소개](https://aws.amazon.com/blogs/aws/getting-started-with-using-your-favorite-operational-tools-on-aws-lambda-extensions-are-now-generally-available/)를 참조하세요. 이 섹션에서는 Lambda 확장 API, Lambda 실행 환경 수명 주기 및 Lambda 확장 API 참조를 사용하는 방법을 설명합니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/telemetry-api-concept-diagram.png)
익스텐션 작성자는 Lambda 익스텐션 API를 사용하여 Lambda [실행 환경](lambda-runtime-environment.md)과 완전히 통합할 수 있습니다. 익스텐션은 함수 및 실행 환경 수명 주기 이벤트에 등록할 수 있습니다. 이러한 이벤트에 대한 응답으로 새 프로세스를 시작하고, 논리를 실행하고, Lambda 수명 주기의 모든 단계(초기화, 호출 및 종료)를 관리하고 참여할 수 있습니다. 또한 [런타임 로그 API](runtimes-logs-api.md)를 사용하여 로그 스트림을 수신할 수 있습니다.
익스텐션은 실행 환경에서 독립 프로세스로 실행되며 함수 호출이 완전히 처리된 후에도 계속 실행됩니다. 익스텐션은 프로세스로 실행되므로 함수와 다른 언어로 작성할 수 있습니다. 컴파일된 언어를 사용하여 익스텐션을 구현하는 것이 좋습니다. 이 경우 익스텐션은 지원되는 런타임과 호환되는 독립형 바이너리입니다. 모든 [Lambda 런타임](lambda-runtimes.md)은 익스텐션을 지원합니다. 컴파일되지 않은 언어를 사용하는 경우 호환되는 런타임을 익스텐션에 포함해야 합니다.
Lambda는 *내부 익스텐션*도 지원합니다. 내부 익스텐션은 런타임 프로세스에서 별도의 스레드로 실행됩니다. 런타임은 내부 익스텐션을 시작하고 중지합니다. Lambda 환경과 통합하는 다른 방법은 언어별 [환경 변수 및 래퍼 스크립트](runtimes-modify.md)를 사용하는 것입니다. 이 방법을 통해 런타임 환경을 구성하고 런타임 프로세스의 시작 동작을 수정할 수 있습니다.
두 가지 방법으로 익스텐션을 함수에 추가할 수 있습니다. [.zip 파일 아카이브](configuration-function-zip.md)로 배포된 함수의 경우 익스텐션을 [계층](chapter-layers.md)으로 배포합니다. 컨테이너 이미지로 정의된 함수의 경우 [익스텐션](extensions-configuration.md#invocation-extensions-images)을 컨테이너 이미지에 추가합니다.
**참고**
예제 익스텐션 및 래퍼 스크립트에 대해서는 AWS Lambda 샘플 GitHub 리포지토리에서 [AWS 익스텐션](https://github.com/aws-samples/aws-lambda-extensions)을 참조하세요.
**Topics**
+ [
## Lambda 실행 환경 수명 주기
](#runtimes-extensions-api-lifecycle)
+ [
## 익스텐션 API 참조
](#runtimes-extensions-registration-api)
## Lambda 실행 환경 수명 주기
실행 환경의 수명 주기에는 다음 단계가 포함됩니다.
+ `Init`: 이 단계 중에 Lambda는 구성된 리소스로 실행 환경을 만들거나 고정 해제하고, 함수와 모든 계층의 코드를 다운로드하고, 모든 익스텐션을 초기화하고, 런타임을 초기화한 다음 함수의 초기화 코드(기본 핸들러 외부의 코드)를 실행합니다. `Init` 단계는 첫 번째 호출 중에 발생하거나, [프로비저닝된 동시성](provisioned-concurrency.md)을 사용하도록 설정한 경우 함수 호출 전에 발생합니다.
`Init` 단계는 세 가지 하위 단계(`Extension init`, `Runtime init`, `Function init`.)로 나뉩니다. 이러한 하위 단계는 함수 코드가 실행되기 전에 모든 익스텐션과 런타임이 자신의 설정 작업을 완료하도록 보장합니다.
+ `Invoke`: 이 단계에서 Lambda는 함수 핸들러를 간접 호출합니다. 함수의 실행이 완료한 후 Lambda는 다른 함수 호출을 처리할 준비를 합니다.
+ `Shutdown`: Lambda 함수가 일정 기간 동안 호출을 받지 않으면 이 단계가 트리거됩니다. `Shutdown` 단계에서 Lambda는 런타임을 종료하고 익스텐션이 완전히 중지되도록 알림을 보낸 다음 환경을 제거합니다. Lambda는 각 익스텐션에 `Shutdown` 이벤트를 보냅니다. 이 이벤트는 환경이 곧 종료됨을 익스텐션에 알립니다.
각 단계는 Lambda에서 런타임 및 등록된 모든 익스텐션에 전송하는 이벤트로 시작됩니다. 런타임 및 각 익스텐션이 `Next` API 요청을 전송하여 완료 신호를 보냅니다. 각 프로세스가 완료되고 대기 중인 이벤트가 없으면 Lambda는 실행 환경을 중지합니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/Overview-Full-Sequence.png)
**Topics**
+ [
### 초기화 단계
](#runtimes-extensions-api-reg)
+ [
### 간접 호출 단계
](#runtimes-lifecycle-extensions-invoke)
+ [
### 종료 단계
](#runtimes-lifecycle-extensions-shutdown)
+ [
### 권한 및 구성
](#runtimes-extensions-registration-api-e)
+ [
### 장애 처리
](#runtimes-extensions-api-failure)
+ [
### 익스텐션 문제 해결
](#runtimes-extensions-api-trbl)
### 초기화 단계
`Extension init` 단계 중에 이벤트를 수신하려면 각 익스텐션은 Lambda에 등록해야 합니다. Lambda는 익스텐션의 전체 파일 이름을 사용하여 익스텐션이 부트스트랩 시퀀스를 완료했는지 확인합니다. 따라서 각 `Register` API 호출에는 익스텐션의 전체 파일 이름이 있는 `Lambda-Extension-Name` 헤더를 포함해야 합니다.
각 함수에 최대 10개의 익스텐션을 등록할 수 있습니다. 이 제한은 `Register` API 호출을 통해 적용됩니다.
각 익스텐션이 등록되면 Lambda는 `Runtime init` 단계를 시작합니다. 런타임 프로세스는 `functionInit`를 호출하여 `Function init` 단계를 시작합니다.
`Init` 단계는 런타임 및 등록된 각 익스텐션이 `Next` API 요청을 전송하여 완료를 나타낸 후에 완료됩니다.
**참고**
익스텐션은 `Init` 단계의 어느 지점에서나 초기화를 완료할 수 있습니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/Init-Phase.png)
### 간접 호출 단계
`Next` API 요청에 대한 응답으로 Lambda 함수가 간접 호출되면 Lambda는 런타임과 `Invoke` 이벤트에 등록된 각 익스텐션에 `Invoke` 이벤트를 전송합니다.
**참고**
**Lambda 관리형 인스턴스:** Lambda 관리형 인스턴스 함수의 확장은 `Invoke` 이벤트에 등록할 수 없습니다. Lambda 관리형 인스턴스는 단일 실행 환경 내에서 동시 간접 호출을 지원하므로 `Invoke` 이벤트는 지원되지 않습니다. 확장은 `Shutdown` 이벤트에만 등록할 수 있습니다. 간접 호출 시작 및 완료 시기를 추적해야 하는 경우 [텔레메트리 API](telemetry-api.md)를 통해 `platform.report` 플랫폼 이벤트를 사용합니다.
호출하는 동안 외부 익스텐션은 함수와 동시에 실행됩니다. 또한 함수가 완료된 후에도 외부 익스텐션이 계속 실행됩니다. 따라서 진단 정보를 캡처하거나 로그, 지표 및 추적 정보를 선택한 위치로 보낼 수 있습니다.
런타임에서 함수 응답을 수신한 후 Lambda는 익스텐션이 여전히 실행 중이더라도 클라이언트에 대한 응답을 반환합니다.
`Invoke` 단계는 런타임 및 모든 익스텐션이 `Next` API 요청을 전송하여 완료되었음을 알린 후에 종료됩니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/Invoke-Phase.png)
**이벤트 페이로드**: 런타임(및 Lambda 함수)으로 전송되는 이벤트에는 전체 요청, 헤더(예: `RequestId`) 및 페이로드가 포함됩니다. 각 익스텐션으로 전송되는 이벤트에는 이벤트 내용을 설명하는 메타데이터가 포함됩니다. 이 수명 주기 이벤트에는 이벤트 유형, 함수가 시간 초과되는 시간(`deadlineMs`), `requestId`, 간접 호출된 함수의 Amazon 리소스 이름(ARN) 및 추적 헤더가 포함됩니다.
함수 이벤트 본문에 액세스하려는 익스텐션은 익스텐션과 통신하는 런타임 내 SDK를 사용할 수 있습니다. 함수 개발자는 런타임 내 SDK를 사용하여 함수가 간접 호출될 때 익스텐션에 페이로드를 전송합니다.
다음은 페이로드의 예입니다.
```
{
"eventType": "INVOKE",
"deadlineMs": 676051,
"requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
"invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",
"tracing": {
"type": "X-Amzn-Trace-Id",
"value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
}
}
```
**기간 제한**: 함수의 제한 시간 설정은 전체 `Invoke` 단계의 기간을 제한합니다. 예를 들어 함수 제한 시간을 360초로 설정하면 함수와 모든 익스텐션이 360초 내에 완료되어야 합니다. 독립적인 간접 호출 후 단계는 없습니다. 기간은 런타임 및 모든 확장의 호출이 완료되는 데 걸리는 총 시간이며 함수와 모든 확장의 실행이 완료될 때까지 계산되지 않습니다.
**성능 영향 및 익스텐션 오버헤드**: 익스텐션은 함수 성능에 영향을 줄 수 있습니다. 익스텐션 작성자는 익스텐션이 성능에 미치는 영향을 제어할 수 있습니다. 예를 들어 익스텐션이 컴퓨팅 집약적 작업을 수행하는 경우 함수 소요 시간이 늘어납니다. 익스텐션과 함수 코드가 동일한 CPU 리소스를 공유하기 때문입니다. 또한 함수 호출이 완료된 후 익스텐션에서 대규모 연산을 수행하는 경우 모든 익스텐션이 완료되었음을 알릴 때까지 `Invoke` 단계가 계속되므로 함수 소요 시간이 늘어납니다.
**참고**
Lambda는 함수의 메모리 설정에 비례하여 CPU 용량을 할당합니다. 함수 및 익스텐션 프로세스가 동일한 CPU 리소스를 놓고 경쟁하기 때문에 낮은 메모리 설정에서 실행 및 초기화 기간이 늘어날 수 있습니다. 실행 및 초기화 기간을 줄이려면 메모리 설정을 늘려보세요.
`Invoke` 단계에서 익스텐션에 의한 성능 영향을 식별할 수 있도록 Lambda는 `PostRuntimeExtensionsDuration` 지표를 출력합니다. 이 지표는 런타임 `Next` API 요청과 마지막 익스텐션 `Next` API 요청 사이의 누적 시간을 측정합니다. 사용된 메모리 증가를 측정하려면 `MaxMemoryUsed` 지표를 사용합니다. 함수 지표에 대한 자세한 내용은 [Lambda에서 CloudWatch 지표 사용](monitoring-metrics.md) 섹션을 참조하세요.
함수 개발자는 다양한 버전의 함수를 나란히 실행하여 특정 익스텐션의 영향을 파악할 수 있습니다. 익스텐션 작성자는 함수 개발자가 적합한 익스텐션을 쉽게 선택할 수 있도록 예상되는 리소스 소비를 게시하는 것이 좋습니다.
### 종료 단계
Lambda는 런타임을 종료하려고 할 때 `Shutdown`을 등록된 각 외부 익스텐션에 전송합니다. 익스텐션은 이 시간 동안 최종 정리 작업을 수행할 수 있습니다. `Shutdown` 이벤트는 `Next` API 요청에 대한 응답으로 전송됩니다.
**기간 제한**: `Shutdown` 단계의 최대 기간은 등록된 익스텐션 구성에 따라 다릅니다.
+ 0밀리초 - 등록된 익스텐션이 없는 함수
+ 500밀리초 - 등록된 내부 익스텐션이 하나 있는 함수
+ 2,000밀리초 - 등록된 외부 익스텐션이 하나 이상 있는 함수
런타임 또는 익스텐션이 제한 시간 내에 `Shutdown` 이벤트에 응답하지 않는 경우 Lambda는 `SIGKILL` 신호를 사용하여 프로세스를 종료합니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/Shutdown-Phase.png)
**이벤트 페이로드**: `Shutdown` 이벤트에는 종료 이유와 남은 시간(밀리초)이 포함됩니다.
`shutdownReason`에는 다음과 같은 값이 포함됩니다.
+ SPINDOWN - 정상 종료
+ TIMEOUT - 기간 제한 초과
+ FAILURE - 오류 상태(예: `out-of-memory` 이벤트)
```
{
"eventType": "SHUTDOWN",
"shutdownReason": "reason for shutdown",
"deadlineMs": "the time and date that the function times out in Unix time milliseconds"
}
```
### 권한 및 구성
익스텐션은 Lambda 함수와 동일한 실행 환경에서 실행됩니다. 익스텐션은 CPU, 메모리, `/tmp` 디스크 스토리지와 같은 리소스를 함수와 공유합니다. 또한 익스텐션은 함수와 동일한 AWS Identity and Access Management(IAM) 역할 및 보안 컨텍스트를 사용합니다.
**파일 시스템 및 네트워크 액세스 권한**: 익스텐션은 함수 런타임과 동일한 파일 시스템 및 네트워크 이름 네임스페이스에서 실행됩니다. 따라서 익스텐션은 해당 운영 체제와 호환되어야 합니다. 익스텐션에 추가 아웃바운드 네트워크 트래픽 규칙이 필요한 경우 이러한 규칙을 함수 구성에 적용해야 합니다.
**참고**
함수 코드 디렉터리는 읽기 전용이므로 익스텐션에서 함수 코드를 수정할 수 없습니다.
**환경 변수**: 익스텐션은 런타임 프로세스와 관련된 다음 변수를 제외하고 함수의 [환경 변수](configuration-envvars.md)에 액세스할 수 있습니다.
+ `AWS_EXECUTION_ENV`
+ `AWS_LAMBDA_LOG_GROUP_NAME`
+ `AWS_LAMBDA_LOG_STREAM_NAME`
+ `AWS_XRAY_CONTEXT_MISSING`
+ `AWS_XRAY_DAEMON_ADDRESS`
+ `LAMBDA_RUNTIME_DIR`
+ `LAMBDA_TASK_ROOT`
+ `_AWS_XRAY_DAEMON_ADDRESS`
+ `_AWS_XRAY_DAEMON_PORT`
+ `_HANDLER`
**참고**
**Lambda 관리형 인스턴스 감지:** 확장은 `AWS_LAMBDA_INITIALIZATION_TYPE` 환경 변수를 확인하여 Lambda 관리형 인스턴스 또는 Lambda(기본값) 함수에서 실행 중인지 여부를 확인할 수 있습니다. 확장이 실행 환경 유형에 따라 동작을 조정하는 데 권장되는 방법입니다.
### 장애 처리
**초기화 오류**: 익스텐션에 오류가 발생하면 Lambda는 실행 환경을 다시 시작하여 일관된 동작을 적용하고 익스텐션에 대해 빠른 실패(fast fail)를 장려합니다. 또한 일부 고객의 경우 익스텐션이 로깅, 보안, 거버넌스 및 텔레메트리 수집과 같은 미션 크리티컬한 요구 사항을 충족해야 합니다.
**간접 호출 오류**(예: 메모리 부족, 함수 시간 초과): 익스텐션은 런타임과 리소스를 공유하므로 메모리 부족의 영향을 받습니다. 런타임에 오류가 발생하면 모든 익스텐션과 런타임 자체가 `Shutdown` 단계에 참여합니다. 또한 런타임은 현재 호출의 일부로 자동으로 다시 시작되거나 지연된 재초기화 메커니즘을 통해 다시 시작됩니다.
함수 시간 초과 또는 런타임 오류와 같은 오류가 발생하면 `Invoke` 시 Lambda 서비스가 재설정을 수행합니다. 재설정은 `Shutdown` 이벤트처럼 동작합니다. 먼저 Lambda는 런타임을 종료한 다음 등록된 각 외부 익스텐션에 `Shutdown` 이벤트를 전송합니다. 이벤트에는 종료 이유가 포함됩니다. 이 환경이 새 호출에 사용되는 경우 익스텐션 및 런타임은 다음 호출의 일부로 다시 초기화됩니다.
![\[실행 환경 예시: 초기화, 간접 호출, 오류가 있는 간접 호출, 간접 호출, 종료\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/Overview-Invoke-with-Error.png)
이전 다이어그램에 대한 자세한 설명은 [간접 호출 단계 중 실패](lambda-runtime-environment.md#runtimes-lifecycle-invoke-with-errors)을 참조하십시오.
**익스텐션 로그**: Lambda가 익스텐션의 로그 출력을 CloudWatch Logs에 보냅니다. Lambda는 `Init` 시 각 익스텐션에 대한 추가 로그 이벤트도 생성합니다. 로그 이벤트에는 성공 시 이름 및 등록 기본 설정(이벤트, 구성)과 실패 시 실패 이유가 기록됩니다.
### 익스텐션 문제 해결
+ `Register` 요청이 실패할 경우 `Lambda-Extension-Name` API 호출의 `Register` 헤더에 익스텐션의 전체 파일 이름이 포함되어 있는지 확인합니다.
+ 내부 익스텐션에 대한 `Register` 요청이 실패할 경우 요청이 `Shutdown` 이벤트에 등록되지 않았는지 확인합니다.
## 익스텐션 API 참조
익스텐션 API 버전 **2020-01-01**에 대한 OpenAPI 사양은 [extensions-api.zip](samples/extensions-api.zip)에서 사용할 수 있습니다.
`AWS_LAMBDA_RUNTIME_API` 환경 변수에서 API 엔드포인트의 값을 검색할 수 있습니다. `Register` 요청을 보내려면 각 API 경로 앞에 접두사 `2020-01-01/`을 사용합니다. 예:
```
http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
```
**Topics**
+ [
### 등록
](#extensions-registration-api-a)
+ [
### 다음
](#extensions-api-next)
+ [
### 초기화 오류
](#runtimes-extensions-init-error)
+ [
### 종료 오류
](#runtimes-extensions-exit-error)
### 등록
`Extension init` 중에 이벤트를 수신하려면 모든 익스텐션은 Lambda에 등록해야 합니다. Lambda는 익스텐션의 전체 파일 이름을 사용하여 익스텐션이 부트스트랩 시퀀스를 완료했는지 확인합니다. 따라서 각 `Register` API 호출에는 익스텐션의 전체 파일 이름이 있는 `Lambda-Extension-Name` 헤더를 포함해야 합니다.
내부 익스텐션은 런타임 프로세스에 의해 시작 및 중지되므로 `Shutdown` 이벤트에 등록할 수 없습니다.
**경로** – `/extension/register`
**메서드** – **POST**
**요청 헤더**
+ `Lambda-Extension-Name` - 익스텐션의 전체 파일 이름입니다. 필수 항목 여부: 예. 유형: 문자열.
+ `Lambda-Extension-Accept-Feature` - 이 옵션을 사용하여 등록 시 선택적 확장 기능을 지정할 수 있습니다. 필수 항목 여부: 아니요 유형: 쉼표로 구분된 문자열입니다. 이 설정을 사용하여 지정할 수 있는 기능은 다음과 같습니다.
+ `accountId` - 지정된 경우 확장 등록 응답에는 확장을 등록하려는 Lambda 함수와 연결된 계정 ID가 포함됩니다.
**요청 본문 파라미터**
+ `events` - 등록할 이벤트의 배열입니다. 필수 항목 여부: 아니요 유형: 문자열 배열 유효한 문자열: `INVOKE`, `SHUTDOWN`.
**참고**
**Lambda 관리형 인스턴스:** Lambda 관리형 인스턴스 함수의 확장은 `SHUTDOWN` 이벤트에만 등록할 수 있습니다. `INVOKE` 이벤트에 등록하려고 하면 오류가 발생합니다. Lambda 관리형 인스턴스는 단일 실행 환경 내에서 동시 간접 호출을 지원하기 때문입니다.
**응답 헤더**
+ `Lambda-Extension-Identifier` - 모든 후속 요청에 필요한, 생성된 고유 에이전트 식별자(UUID 문자열)입니다.
**응답 코드**
+ 200 - 응답 본문에는 함수 이름, 함수 버전 및 핸들러 이름이 포함됩니다.
+ 400 - 잘못된 요청
+ 403 - 금지됨
+ 500 - 컨테이너 오류. 복구 불능 상태입니다. 익스텐션을 즉시 종료해야 합니다.
**Example 요청 본문의 예**
```
{
'events': [ 'INVOKE', 'SHUTDOWN']
}
```
**Example 응답 본문의 예**
```
{
"functionName": "helloWorld",
"functionVersion": "$LATEST",
"handler": "lambda_function.lambda_handler"
}
```
**Example 선택적 accountId 기능이 포함된 응답 본문의 예**
```
{
"functionName": "helloWorld",
"functionVersion": "$LATEST",
"handler": "lambda_function.lambda_handler",
"accountId": "123456789012"
}
```
### 다음
익스텐션은 `Next` API 요청을 전송하여 다음 이벤트(`Invoke` 이벤트 또는 `Shutdown` 이벤트가 될 수 있음)를 수신합니다. 응답 본문에는 이벤트 데이터가 포함된 JSON 문서인 페이로드가 포함되어 있습니다.
익스텐션은 `Next` API 요청을 전송하여 새 이벤트를 수신할 준비가 되었음을 알립니다. 이는 차단 호출입니다.
반환할 이벤트가 발생할 때까지 일정 기간 동안 익스텐션이 일시 중단될 수 있으므로 GET 호출에 시간 제한을 설정하지 마세요.
**경로** – `/extension/event/next`
**매서드** – **GET**
**요청 헤더**
+ `Lambda-Extension-Identifier` - 익스텐션의 고유 식별자(UUID 문자열). 필수 항목 여부: 예. 유형: UUID 문자열.
**응답 헤더**
+ `Lambda-Extension-Event-Identifier` - 이벤트의 고유 식별자(UUID 문자열)입니다.
**응답 코드**
+ 200 - 응답에는 다음 이벤트(`EventInvoke` 또는 `EventShutdown`)에 대한 정보가 포함됩니다.
+ 403 - 금지됨
+ 500 - 컨테이너 오류. 복구 불능 상태입니다. 익스텐션을 즉시 종료해야 합니다.
### 초기화 오류
익스텐션은 이 메서드를 사용하여 Lambda에 초기화 오류를 보고합니다. 익스텐션이 등록된 후 초기화에 실패할 경우 이 메서드를 호출합니다. Lambda가 오류를 수신하면 더 이상 API 호출이 성공하지 못합니다. 익스텐션은 Lambda로부터 응답을 수신한 후에 종료되어야 합니다.
**경로** – `/extension/init/error`
**메서드** – **POST**
**요청 헤더**
+ `Lambda-Extension-Identifier` - 익스텐션의 고유 식별자. 필수 항목 여부: 예. 유형: UUID 문자열.
+ `Lambda-Extension-Function-Error-Type` – 익스텐션에서 발생한 오류 유형입니다. 필수 항목 여부: 예. 이 헤더는 문자열 값으로 구성됩니다. Lambda는 모든 문자열을 허용하지만 형식을 사용하는 것이 좋습니다. 예:
+ Extension.NoSuchHandler
+ Extension.APIKeyNotFound
+ Extension.ConfigInvalid
+ Extension.UnknownReason
**요청 본문 파라미터**
+ `ErrorRequest` – 오류에 대한 정보입니다. 필수 항목 여부: 아니요
이 필드는 다음과 같은 구조의 JSON 객체입니다.
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
Lambda는 `errorType`에 대한 모든 값을 허용합니다.
다음 예제에서는 Lambda 함수가 호출에 제공된 이벤트 데이터를 구문 분석할 수 없는 함수 오류 메시지를 보여 줍니다.
**Example 함수 오류**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**응답 코드**
+ 202 - 수락됨
+ 400 - 잘못된 요청
+ 403 - 금지됨
+ 500 - 컨테이너 오류. 복구 불능 상태입니다. 익스텐션을 즉시 종료해야 합니다.
### 종료 오류
익스텐션은 종료 전에 이 메서드를 사용하여 Lambda에 오류를 보고합니다. 예기치 않은 오류가 발생하면 이 메서드를 호출합니다. Lambda가 오류를 수신하면 더 이상 API 호출이 성공하지 못합니다. 익스텐션은 Lambda로부터 응답을 수신한 후에 종료되어야 합니다.
**경로** – `/extension/exit/error`
**메서드** – **POST**
**요청 헤더**
+ `Lambda-Extension-Identifier` - 익스텐션의 고유 식별자. 필수 항목 여부: 예. 유형: UUID 문자열.
+ `Lambda-Extension-Function-Error-Type` – 익스텐션에서 발생한 오류 유형입니다. 필수 항목 여부: 예. 이 헤더는 문자열 값으로 구성됩니다. Lambda는 모든 문자열을 허용하지만 형식을 사용하는 것이 좋습니다. 예:
+ Extension.NoSuchHandler
+ Extension.APIKeyNotFound
+ Extension.ConfigInvalid
+ Extension.UnknownReason
**요청 본문 파라미터**
+ `ErrorRequest` – 오류에 대한 정보입니다. 필수 항목 여부: 아니요
이 필드는 다음과 같은 구조의 JSON 객체입니다.
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
Lambda는 `errorType`에 대한 모든 값을 허용합니다.
다음 예제에서는 Lambda 함수가 호출에 제공된 이벤트 데이터를 구문 분석할 수 없는 함수 오류 메시지를 보여 줍니다.
**Example 함수 오류**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**응답 코드**
+ 202 - 수락됨
+ 400 - 잘못된 요청
+ 403 - 금지됨
+ 500 - 컨테이너 오류. 복구 불능 상태입니다. 익스텐션을 즉시 종료해야 합니다.
# 텔레메트리 API를 사용하여 확장의 실시간 텔레메트리 데이터에 액세스
텔레메트리 API를 사용하면 확장에서 Lambda로부터 텔레메트리 데이터를 직접 수신할 수 있습니다. 함수 초기화 및 간접 호출 중에 Lambda는 로그, 플랫폼 지표, 플랫폼 트레이스와 같은 텔레메트리를 자동으로 캡처합니다. 텔레메트리 API를 사용하면 확장에서 Lambda로부터 거의 실시간으로 이 텔레메트리 데이터에 직접 액세스할 수 있습니다.
Lambda 실행 환경 내에서 텔레메트리 스트림에 대한 Lambda 확장을 구독할 수 있습니다. 구독 후 Lambda는 모든 텔레메트리 데이터를 확장으로 자동 전송합니다. 그런 다음 유연하게 데이터를 처리 및 필터링하고 Amazon Simple Storage Service(Amazon S3) 버킷 또는 타사 관찰성 도구 제공업체와 같은 원하는 대상으로 전송할 수 있습니다.
다음 다이어그램은 확장 API와 텔레메트리 API가 실행 환경 내에서 확장을 Lambda에 연결하는 방법을 보여줍니다. 또한 런타임 API는 런타임 및 함수를 Lambda에 연결합니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/telemetry-api-concept-diagram.png)
**중요**
Lambda Telemetry API는 Lambda 로그 API를 대체합니다. **로그 API도 계속 정상적으로 작동하지만, 앞으로는 텔레메트리 API만 사용하는 것이 좋습니다.** 텔레메트리 API 또는 로그 API를 사용하여 확장에서 텔레메트리 스트림을 구독할 수 있습니다. 이러한 API 중 하나를 사용하여 구독한 후 다른 API를 사용하여 구독하려고 하면 오류가 반환됩니다.
**Lambda 관리형 인스턴스 스키마 버전 요구 사항**
Lambda 관리형 인스턴스는 `2025-01-29` 텔레메트리 API의 스키마 버전만 지원합니다. 관리형 인스턴스 함수에 대한 텔레메트리 스트림을 구독할 때는 구독 요청에 `"schemaVersion": "2025-01-29"`를 **사용해야 합니다**. 이전 스키마 버전을 사용하면 Lambda에서 이벤트가 거부됩니다.
`2025-01-29` 스키마 버전은 이전 버전과 호환되고 Lambda 관리형 인스턴스 및 Lambda(기본값) 함수에서 사용할 수 있습니다. 두 배포 모델 간의 호환성을 보장하려면 모든 새 확장에 이 버전을 사용하는 것이 좋습니다.
확장은 텔레메트리 API를 사용하여 세 가지 텔레메트리 스트림을 구독할 수 있습니다.
+ **플랫폼 텔레메트리** - 실행 환경 런타임 수명 주기, 확장 수명 주기 및 함수 호출과 관련한 이벤트와 오류를 설명하는 로그, 지표 및 트레이스입니다.
+ **함수 로그** - Lambda 함수 코드가 생성하는 사용자 지정 로그입니다.
+ **확장 로그** - Lambda 확장 코드가 생성하는 사용자 지정 로그입니다.
**참고**
확장이 텔레메트리 스트림을 구독하는 경우에도 Lambda는 CloudWatch로 로그와 지표를 전송하고 X-Ray로 트레이스를 전송합니다(추적을 활성화한 경우).
**Topics**
+ [
## 텔레메트리 API를 사용하여 확장 생성
](#telemetry-api-creating-extensions)
+ [
## 확장 등록
](#telemetry-api-registration)
+ [
## 텔레메트리 리스너 생성
](#telemetry-api-listener)
+ [
## 대상 프로토콜 지정
](#telemetry-api-destination)
+ [
## 메모리 사용량 및 버퍼링 구성
](#telemetry-api-buffering)
+ [
## 텔레메트리 API에 구독 요청 전송
](#telemetry-api-subscription)
+ [
## 인바운드 텔레메트리 API 메시지
](#telemetry-api-messages)
+ [
# Lambda Telemetry API 참조
](telemetry-api-reference.md)
+ [
# Lambda Telemetry API `Event` 스키마 참조
](telemetry-schema-reference.md)
+ [
# Lambda Telemetry API `Event` 객체를 OpenTelemetry 범위로 변환
](telemetry-otel-spans.md)
+ [
# Lambda 로그 API 사용
](runtimes-logs-api.md)
## 텔레메트리 API를 사용하여 확장 생성
Lambda 확장은 실행 환경에서 독립 프로세스로 실행됩니다. 함수 간접 호출이 완료된 후에도 확장을 계속 실행할 수 있습니다. 화장은 별도의 프로세스로 실행되므로 함수 코드와 다른 언어로 작성할 수 있습니다. Golang 또는 Rust와 같은 컴파일된 언어를 사용하여 확장을 작성하는 것이 좋습니다. 이 경우 확장은 지원되는 모든 런타임과 호환되는 독립형 바이너리입니다.
다음 다이어그램은 텔레메트리 API를 사용하여 텔레메트리 데이터를 수신하고 처리하는 확장을 생성하는 4단계 프로세스를 보여줍니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/telemetry-api-creation-steps.png)
다음은 각 단계에 대한 자세한 내용입니다.
1. [Lambda 확장 API를 사용하여 확장 생성](runtimes-extensions-api.md)를 사용하여 확장을 등록합니다. 이렇게 하면 다음 단계에서 필요한 `Lambda-Extension-Identifier`가 제공됩니다. 확장을 등록하는 자세한 방법은 [확장 등록](#telemetry-api-registration) 섹션을 참조하세요.
1. 텔레메트리 리스너를 생성합니다. 기본 HTTP 또는 TCP 서버일 수 있습니다. Lambda는 텔레메트리 리스너의 URI를 사용하여 텔레메트리 데이터를 확장에 전송합니다. 자세한 내용은 [텔레메트리 리스너 생성](#telemetry-api-listener) 섹션을 참조하세요.
1. 텔레메트리 API에서 구독 API를 사용하여 원하는 텔레메트리 스트림에 대한 확장을 구독합니다. 이 단계에는 텔레메트리 리스너의 URI가 필요합니다. 자세한 내용은 [텔레메트리 API에 구독 요청 전송](#telemetry-api-subscription) 섹션을 참조하세요.
1. 텔레메트리 리스너를 통해 Lambda에서 텔레메트리 데이터를 가져옵니다. Amazon S3나 외부 관측성 서비스로 데이터를 디스패치하는 등 이 데이터에 대한 모든 사용자 지정 처리 작업을 수행할 수 있습니다.
**참고**
Lambda 함수의 실행 환경은 [수명 주기](runtimes-extensions-api.md#runtimes-extensions-api-lifecycle)의 일부로 여러 번 시작 및 중지할 수 있습니다. 일반적으로 확장 코드는 함수 호출 중에 실행되며 종료 단계에서도 최대 2초간 실행됩니다. 텔레메트리가 리스너에 도착하면 일괄 처리하는 것이 좋습니다. 그런 다음, `Invoke` 및 `Shutdown` 수명 주기 이벤트를 사용하여 각 배치를 원하는 대상으로 전송합니다.
## 확장 등록
텔레메트리 데이터를 구독하려면 먼저 Lambda 확장을 등록해야 합니다. 등록은 [확장 초기화 단계](runtimes-extensions-api.md#runtimes-extensions-api-reg)에서 이루어집니다. 다음 예제에서는 확장을 등록하는 HTTP 요청을 보여줍니다.
```
POST http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
Lambda-Extension-Name: lambda_extension_name
{
'events': [ 'INVOKE', 'SHUTDOWN']
}
```
요청이 성공하면 구독자는 HTTP 200 성공 응답을 받습니다. 응답 헤더에는 `Lambda-Extension-Identifier`가 포함되어 있습니다. 응답 본문에는 함수의 다른 속성이 포함되어 있습니다.
```
HTTP/1.1 200 OK
Lambda-Extension-Identifier: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{
"functionName": "lambda_function",
"functionVersion": "$LATEST",
"handler": "lambda_handler",
"accountId": "123456789012"
}
```
자세한 내용은 [익스텐션 API 참조](runtimes-extensions-api.md#runtimes-extensions-registration-api)을 참조하세요.
## 텔레메트리 리스너 생성
Lambda 확장에는 텔레메트리 API로부터 수신되는 요청을 처리하는 리스너가 있어야 합니다. 다음 코드는 Golang의 텔레메트리 리스너 구현 예제를 보여줍니다.
```
// Starts the server in a goroutine where the log events will be sent
func (s *TelemetryApiListener) Start() (string, error) {
address := listenOnAddress()
l.Info("[listener:Start] Starting on address", address)
s.httpServer = &http.Server{Addr: address}
http.HandleFunc("/", s.http_handler)
go func() {
err := s.httpServer.ListenAndServe()
if err != http.ErrServerClosed {
l.Error("[listener:goroutine] Unexpected stop on Http Server:", err)
s.Shutdown()
} else {
l.Info("[listener:goroutine] Http Server closed:", err)
}
}()
return fmt.Sprintf("http://%s/", address), nil
}
// http_handler handles the requests coming from the Telemetry API.
// Everytime Telemetry API sends log events, this function will read them from the response body
// and put into a synchronous queue to be dispatched later.
// Logging or printing besides the error cases below is not recommended if you have subscribed to
// receive extension logs. Otherwise, logging here will cause Telemetry API to send new logs for
// the printed lines which may create an infinite loop.
func (s *TelemetryApiListener) http_handler(w http.ResponseWriter, r *http.Request) {
body, err := ioutil.ReadAll(r.Body)
if err != nil {
l.Error("[listener:http_handler] Error reading body:", err)
return
}
// Parse and put the log messages into the queue
var slice []interface{}
_ = json.Unmarshal(body, &slice)
for _, el := range slice {
s.LogEventsQueue.Put(el)
}
l.Info("[listener:http_handler] logEvents received:", len(slice), " LogEventsQueue length:", s.LogEventsQueue.Len())
slice = nil
}
```
## 대상 프로토콜 지정
텔레메트리를 수신하기 위해 텔레메트리 API를 사용하여 구독하는 경우, 대상 URI 외에 대상 프로토콜도 지정할 수 있습니다.
```
{
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
}
```
Lambda는 텔레메트리를 수신하는 데 두 가지 프로토콜을 허용합니다.
+ **HTTP(권장)** – Lambda가 텔레메트리를 로컬 HTTP 엔드포인트(`http://sandbox.localdomain:${PORT}/${PATH}`)에 JSON 형식의 레코드 배열로 전달합니다. `$PATH` 파라미터는 선택 항목입니다. Lambda는 HTTP만 지원하고 HTTPS는 지원하지 않습니다. Lambda는 POST 요청을 통해 텔레메트리를 제공합니다.
+ **TCP** – Lambda가 텔레메트리를 [새 줄 구분 JSON(NDJSON) 형식](https://github.com/ndjson/ndjson-spec)으로 TCP 포트에 전달합니다.
**참고**
TCP 대신 HTTP를 사용하는 것이 좋습니다. TCP를 사용하면 Lambda 플랫폼에서는 텔레메트리를 애플리케이션 계층에 전송할 때 인식할 수 없습니다. 따라서 확장이 작동 중지될 경우 텔레메트리가 손실될 수 있습니다. HTTP에는 이러한 제한이 없습니다.
텔레메트리 수신을 위해 구독하기 전에 로컬 HTTP 리스너 또는 TCP 포트를 설정합니다. 설치하는 동안 다음 사항에 유의하세요.
+ Lambda는 실행 환경 내에 있는 대상에만 텔레메트리를 보냅니다.
+ Lambda는 리스너가 없거나 POST 요청에서 오류가 발생하는 경우 텔레메트리 전송을 다시 시도합니다(백오프 포함). 텔레메트리 리스너에서 충돌이 발생하는 경우 Lambda가 실행 환경을 다시 시작한 후 텔레메트리를 계속 수신합니다.
+ Lambda는 포트 9001을 예약합니다. 다른 포트 번호 제한이나 권장 사항은 없습니다.
## 메모리 사용량 및 버퍼링 구성
실행 환경에서 메모리 사용량은 구독자 수에 따라 선형적으로 증가합니다. 각 구독은 새 메모리 버퍼를 열어 텔레메트리 데이터를 저장하기 때문에 메모리 리소스를 사용합니다. 버퍼 메모리 사용량은 실행 환경의 전체 메모리 소비에 포함됩니다.
텔레메트리 API를 사용하여 텔레메트리를 수신하기 위해 구독하면 텔레메트리 데이터를 버퍼링하여 구독자에게 배치로 전달하는 옵션이 제공됩니다. 메모리 사용량을 최적화하기 위해 버퍼링 구성을 지정할 수 있습니다.
```
{
"buffering": {
"maxBytes": 256*1024,
"maxItems": 1000,
"timeoutMs": 100
}
}
```
| 파라미터 | 설명 | 기본값 및 한도 |
| --- | --- | --- |
| `maxBytes` | 메모리에 버퍼링할 텔레메트리의 최대 볼륨(바이트)입니다. | 기본값: 26만 2,144 최소: 26만 2,144 최대: 1,04만 8,576 |
| `maxItems` | 메모리에 버퍼링할 최대 이벤트 수입니다. | 기본값: 1만 최소: 1,000 최대값: 10,000 |
| `timeoutMs` | 배치를 버퍼링할 최대 시간(밀리초)입니다. | 기본값: 1,000 최소: 25 최대: 30,000 |
버퍼링을 설정할 때 다음 사항을 고려합니다.
+ 입력 스트림이 닫히면 Lambda가 로그를 플러시합니다. 예를 들어 런타임에서 충돌이 발생한 경우 이 상황이 나타날 수 있습니다.
+ 각 구독자는 구독 요청에서 버퍼링 구성을 사용자 지정할 수 있습니다.
+ 데이터를 읽기 위한 버퍼 크기를 결정할 때 수신 페이로드를 최대 `2 * maxBytes + metadataBytes`로 예상합니다. 여기서, `maxBytes`는 버퍼링 설정의 구성 요소입니다. 고려할 `metadataBytes`의 크기를 측정하려면 다음 메타데이터를 검토합니다. Lambda는 다음과 유사한 메타데이터를 각 레코드에 추가합니다.
```
{
"time": "2022-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}
```
+ 구독자가 들어오는 텔레메트리를 충분히 빠르게 처리할 수 없거나 함수 코드가 매우 높은 로그 볼륨을 생성하는 경우 Lambda는 메모리 사용률을 범위 내로 유지하기 위해 레코드를 삭제할 수 있습니다. 이 경우 Lambda는 `platform.logsDropped` 이벤트를 전송합니다.
## 텔레메트리 API에 구독 요청 전송
Lambda 확장은 텔레메트리 API에 구독 요청을 전송하여 텔레메트리 데이터를 수신하도록 구독할 수 있습니다. 이 구독 요청에는 확장이 구독하도록 하려는 이벤트 유형에 대한 정보가 포함되어야 합니다. 또한 이 요청에는 [전송 대상 정보](#telemetry-api-destination)와 [버퍼링 구성](#telemetry-api-buffering)이 포함될 수 있습니다.
구독 요청을 전송하려면 먼저 확장 ID(`Lambda-Extension-Identifier`)가 있어야 합니다. [확장 API를 사용하여 확장을 등록](#telemetry-api-registration)할 때 API 응답에서 확장 ID를 얻습니다.
구독은 [확장 초기화 단계](runtimes-extensions-api.md#runtimes-extensions-api-reg)에서 이루어집니다. 다음 예에서는 플랫폼 텔레메트리, 함수 로그, 확장 로그의 세 가지 텔레메트리 스트림을 모두 구독하는 HTTP 요청을 보여줍니다.
```
PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
"schemaVersion": "2025-01-29",
"types": [
"platform",
"function",
"extension"
],
"buffering": {
"maxItems": 1000,
"maxBytes": 256*1024,
"timeoutMs": 100
},
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
}
```
요청이 성공하면 구독자는 HTTP 200 성공 응답을 받습니다.
```
HTTP/1.1 200 OK
"OK"
```
## 인바운드 텔레메트리 API 메시지
텔레메트리 API를 사용하여 구독하고 나면 확장이 POST 요청을 통해 Lambda로부터 텔레메트리를 자동으로 수신하기 시작합니다. 각 POST 요청 본문에는 `Event` 객체 배열이 포함되어 있습니다. 각 `Event`에는 다음 스키마가 있습니다.
```
{
time: String,
type: String,
record: Object
}
```
+ `time` 속성은 Lambda 플랫폼에서 이벤트를 생성한 시점을 정의합니다. 이벤트가 실제로 발생한 시점과는 다릅니다. `time`의 문자열 값은 ISO 8601 형식의 타임스탬프입니다.
+ `type` 속성은 이벤트 유형을 정의합니다. 다음 표에서는 모든 가능한 값을 설명합니다.
+ `record` 속성은 텔레메트리 데이터가 포함된 JSON 객체를 정의합니다. 이 JSON 객체의 스키마는 `type`에 따라 달라집니다.
**동시 간접 호출을 통한 이벤트 순서 지정**
[Lambda 관리형 인스턴스](lambda-managed-instances.md)의 경우 동일한 실행 환경 내에서 여러 함수 간접 호출을 동시에 실행할 수 있습니다. 이 경우 서로 다른 동시 간접 호출 간에 `platform.start` 및 `platform.report` 이벤트의 순서가 보장되지 않습니다. 확장은 병렬로 실행되는 여러 간접 호출의 이벤트를 처리해야 하며, 순차적 순서를 가정해서는 안 됩니다.
이벤트를 특정 간접 호출에 올바르게 연결하려면 확장에서 이러한 플랫폼 이벤트에 있는 `requestId` 필드를 사용해야 합니다. 각 간접 호출에는 해당 간접 호출에 대한 모든 이벤트에서 일관성을 유지하는 고유한 요청 ID가 있으므로 순서가 맞지 않는 경우에도 확장에서 이벤트를 올바르게 상호 연관시킬 수 있습니다.
다음 표에는 모든 유형의 `Event` 객체가 요약되어 있으며 각 이벤트 유형의 [텔레메트리 API`Event` 스키마 참조](telemetry-schema-reference.md)에 대한 링크가 나와 있습니다.
| 카테고리 | 이벤트 유형 | 설명 | 이벤트 레코드 스키마 |
| --- | --- | --- | --- |
| 플랫폼 이벤트 | `platform.initStart` | 함수 초기화가 시작되었습니다. | [`platform.initStart`](telemetry-schema-reference.md#platform-initStart) 스키마 |
| 플랫폼 이벤트 | `platform.initRuntimeDone` | 함수 초기화가 완료되었습니다. | [`platform.initRuntimeDone`](telemetry-schema-reference.md#platform-initRuntimeDone) 스키마 |
| 플랫폼 이벤트 | `platform.initReport` | 함수 초기화 보고서입니다. | [`platform.initReport`](telemetry-schema-reference.md#platform-initReport) 스키마 |
| 플랫폼 이벤트 | `platform.start` | 함수 호출이 시작되었습니다. | [`platform.start`](telemetry-schema-reference.md#platform-start) 스키마 |
| 플랫폼 이벤트 | `platform.runtimeDone` | 런타임이 이벤트 처리를 성공 또는 실패로 완료했습니다. | [`platform.runtimeDone`](telemetry-schema-reference.md#platform-runtimeDone) 스키마 |
| 플랫폼 이벤트 | `platform.report` | 함수 호출 보고서입니다. | [`platform.report`](telemetry-schema-reference.md#platform-report) 스키마 |
| 플랫폼 이벤트 | `platform.restoreStart` | 런타임 복원이 시작되었습니다. | [`platform.restoreStart`](telemetry-schema-reference.md#platform-restoreStart) 스키마 |
| 플랫폼 이벤트 | `platform.restoreRuntimeDone` | 런타임 복원이 완료되었습니다. | [`platform.restoreRuntimeDone`](telemetry-schema-reference.md#platform-restoreRuntimeDone) 스키마 |
| 플랫폼 이벤트 | `platform.restoreReport` | 런타임 복원 보고서. | [`platform.restoreReport`](telemetry-schema-reference.md#platform-restoreReport) 스키마 |
| 플랫폼 이벤트 | `platform.telemetrySubscription` | 텔레메트리 API를 구독하는 확장입니다. | [`platform.telemetrySubscription`](telemetry-schema-reference.md#platform-telemetrySubscription) 스키마 |
| 플랫폼 이벤트 | `platform.logsDropped` | Lambda가 로그 항목을 삭제했습니다. | [`platform.logsDropped`](telemetry-schema-reference.md#platform-logsDropped) 스키마 |
| 함수 로그 | `function` | 함수 코드의 로그 줄입니다. | [`function`](telemetry-schema-reference.md#telemetry-api-function) 스키마 |
| 익스텐션 로그 | `extension` | 확장 코드의 로그 줄입니다. | [`extension`](telemetry-schema-reference.md#telemetry-api-extension) 스키마 |
# Lambda Telemetry API 참조
Lambda Telemetry API 엔드포인트를 사용하여 텔레메트리 스트림에 대한 확장을 구독할 수 있습니다. `AWS_LAMBDA_RUNTIME_API` 환경 변수에서 텔레메트리 API 엔드포인트를 검색할 수 있습니다. API 요청을 보내려면 API 버전(`2022-07-01/`) 및 `telemetry/`를 추가합니다. 예제:
```
http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/
```
구독 응답 버전 `2025-01-29`의 OpenAPI 사양(OAS) 정의는 다음을 참조하세요.
+ **HTTP** – [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip)
+ **TCP** – [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip)
**Topics**
+ [
## 구독
](#telemetry-subscribe-api)
## 구독
Lambda 확장은 텔레메트리 스트림을 구독하기 위해 구독 API 요청을 보낼 수 있습니다.
+ **경로** – `/telemetry`
+ **메서드** – `PUT`
+ **헤더**:
+ `Content-Type`: `application/json`
+ **요청 본문 파라미터**
+ **schemaVersion**
+ 필수 여부: 예
+ 유형: String
+ 유효값: `"2025-01-29"`, `"2022-12-13"` 또는 `"2022-07-01"`
+ **참고:** Lambda 관리형 인스턴스에는 `"2025-01-29"`가 필요합니다 이 버전은 Lambda(기본값) 함수와 역호환됩니다.
+ **대상** - 텔레메트리 이벤트 대상과 이벤트 전달을 위한 프로토콜을 정의하는 구성 설정입니다.
+ 필수 여부: 예
+ 유형: 객체
```
{
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
```
+ **프로토콜** - Lambda가 텔레메트리 데이터를 전송하는 데 사용하는 프로토콜입니다.
+ 필수 여부: 예
+ 유형: String
+ 유효한 값: `"HTTP"`\$1`"TCP"`
+ **URI** - 텔레메트리 데이터를 전송할 URI입니다.
+ 필수 여부: 예
+ 유형: String
+ 자세한 내용은 [대상 프로토콜 지정](telemetry-api.md#telemetry-api-destination) 섹션을 참조하세요.
+ **유형** - 확장에서 구독하려는 텔레메트리 유형입니다.
+ 필수 여부: 예
+ 유형: 문자열 배열
+ 유효한 값: `"platform"`\$1`"function"`\$1`"extension"`
+ **버퍼링** - 이벤트 버퍼링을 위한 구성 설정입니다.
+ 필수 여부: 아니요
+ 유형: 객체
```
{
"buffering": {
"maxItems": 1000,
"maxBytes": 256*1024,
"timeoutMs": 100
}
}
```
+ **maxItems** – 메모리에 버퍼링할 최대 이벤트 수입니다.
+ 필수 여부: 아니요
+ 유형: 정수
+ 기본값: 1,000
+ 최소: 1,000
+ 최대값: 10,000
+ **maxBytes** – 메모리에 버퍼링할 텔레메트리의 최대 볼륨(바이트)입니다.
+ 필수 여부: 아니요
+ 유형: 정수
+ 기본값: 26만 2,144
+ 최소: 26만 2,144
+ 최대: 104만 8,576
+ **timeoutMs** – 배치를 버퍼링할 최대 시간(밀리초)입니다.
+ 필수 여부: 아니요
+ 유형: 정수
+ 기본값: 1,000
+ 최소: 25
+ 최대: 30,000
+ 자세한 내용은 [메모리 사용량 및 버퍼링 구성](telemetry-api.md#telemetry-api-buffering) 섹션을 참조하세요.
### 구독 API 요청의 예
```
PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
"schemaVersion": "2025-01-29",
"types": [
"platform",
"function",
"extension"
],
"buffering": {
"maxItems": 1000,
"maxBytes": 256*1024,
"timeoutMs": 100
},
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
}
```
구독 요청이 성공하면 이 확장은 HTTP 200 성공 응답을 받습니다.
```
HTTP/1.1 200 OK
"OK"
```
구독 요청이 실패하면 이 확장은 오류 응답을 받습니다. 예제:
```
HTTP/1.1 400 OK
{
"errorType": "ValidationError",
"errorMessage": "URI port is not provided; types should not be empty"
}
```
확장이 수신할 수 있는 몇 가지 추가 응답 코드는 다음과 같습니다.
+ 200 - 요청이 성공적으로 완료되었습니다.
+ 202 - 요청이 수락되었습니다. 로컬 테스트 환경의 구독 요청 응답
+ 400 - 잘못된 요청
+ 500 - 서비스 오류
# Lambda Telemetry API `Event` 스키마 참조
Lambda Telemetry API 엔드포인트를 사용하여 텔레메트리 스트림에 대한 확장을 구독할 수 있습니다. `AWS_LAMBDA_RUNTIME_API` 환경 변수에서 텔레메트리 API 엔드포인트를 검색할 수 있습니다. API 요청을 보내려면 API 버전(`2022-07-01/`) 및 `telemetry/`를 추가합니다. 예제:
```
http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/
```
구독 응답 버전 `2025-01-29`의 OpenAPI 사양(OAS) 정의는 다음을 참조하세요.
+ **HTTP** – [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip)
+ **TCP** – [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip)
다음 표에는 텔레메트리 API가 지원하는 모든 유형의 `Event` 객체가 요약되어 있습니다.
| 카테고리 | 이벤트 유형 | 설명 | 이벤트 레코드 스키마 |
| --- | --- | --- | --- |
| 플랫폼 이벤트 | `platform.initStart` | 함수 초기화가 시작되었습니다. | [`platform.initStart`](#platform-initStart) 스키마 |
| 플랫폼 이벤트 | `platform.initRuntimeDone` | 함수 초기화가 완료되었습니다. | [`platform.initRuntimeDone`](#platform-initRuntimeDone) 스키마 |
| 플랫폼 이벤트 | `platform.initReport` | 함수 초기화 보고서입니다. | [`platform.initReport`](#platform-initReport) 스키마 |
| 플랫폼 이벤트 | `platform.start` | 함수 호출이 시작되었습니다. | [`platform.start`](#platform-start) 스키마 |
| 플랫폼 이벤트 | `platform.runtimeDone` | 런타임이 이벤트 처리를 성공 또는 실패로 완료했습니다. | [`platform.runtimeDone`](#platform-runtimeDone) 스키마 |
| 플랫폼 이벤트 | `platform.report` | 함수 호출 보고서입니다. | [`platform.report`](#platform-report) 스키마 |
| 플랫폼 이벤트 | `platform.restoreStart` | 런타임 복원이 시작되었습니다. | [`platform.restoreStart`](#platform-restoreStart) 스키마 |
| 플랫폼 이벤트 | `platform.restoreRuntimeDone` | 런타임 복원이 완료되었습니다. | [`platform.restoreRuntimeDone`](#platform-restoreRuntimeDone) 스키마 |
| 플랫폼 이벤트 | `platform.restoreReport` | 런타임 복원 보고서. | [`platform.restoreReport`](#platform-restoreReport) 스키마 |
| 플랫폼 이벤트 | `platform.telemetrySubscription` | 텔레메트리 API를 구독하는 확장입니다. | [`platform.telemetrySubscription`](#platform-telemetrySubscription) 스키마 |
| 플랫폼 이벤트 | `platform.logsDropped` | Lambda가 로그 항목을 삭제했습니다. | [`platform.logsDropped`](#platform-logsDropped) 스키마 |
| 함수 로그 | `function` | 함수 코드의 로그 줄입니다. | [`function`](#telemetry-api-function) 스키마 |
| 익스텐션 로그 | `extension` | 확장 코드의 로그 줄입니다. | [`extension`](#telemetry-api-extension) 스키마 |
**Contents**
+ [
## 텔레메트리 API `Event` 객체 유형
](#telemetry-api-events)
+ [
### `platform.initStart`
](#platform-initStart)
+ [
### `platform.initRuntimeDone`
](#platform-initRuntimeDone)
+ [
### `platform.initReport`
](#platform-initReport)
+ [
### `platform.start`
](#platform-start)
+ [
### `platform.runtimeDone`
](#platform-runtimeDone)
+ [
### `platform.report`
](#platform-report)
+ [
### `platform.restoreStart`
](#platform-restoreStart)
+ [
### `platform.restoreRuntimeDone`
](#platform-restoreRuntimeDone)
+ [
### `platform.restoreReport`
](#platform-restoreReport)
+ [
### `platform.extension`
](#platform-extension)
+ [
### `platform.telemetrySubscription`
](#platform-telemetrySubscription)
+ [
### `platform.logsDropped`
](#platform-logsDropped)
+ [
### `function`
](#telemetry-api-function)
+ [
### `extension`
](#telemetry-api-extension)
+ [
## 공유 객체 유형
](#telemetry-api-objects)
+ [
### `InitPhase`
](#InitPhase)
+ [
### `InitReportMetrics`
](#InitReportMetrics)
+ [
### `InitType`
](#InitType)
+ [
### `ReportMetrics`
](#ReportMetrics)
+ [
### `RestoreReportMetrics`
](#RestoreReportMetrics)
+ [
### `RuntimeDoneMetrics`
](#RuntimeDoneMetrics)
+ [
### `Span`
](#Span)
+ [
### `Status`
](#Status)
+ [
### `TraceContext`
](#TraceContext)
+ [
### `TracingType`
](#TracingType)
## 텔레메트리 API `Event` 객체 유형
이 섹션에서는 Lambda Telemetry API가 지원하는 `Event` 객체 유형을 자세히 설명합니다. 이벤트 설명에서 물음표(`?`)는 해당 속성이 객체에 없을 수 있음을 나타냅니다.
### `platform.initStart`
`platform.initStart` 이벤트는 함수 초기화 단계가 시작되었음을 나타냅니다. `platform.initStart` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.initStart
- record: PlatformInitStart
```
`PlatformInitStart` 객체에는 다음 속성이 있습니다.
+ **functionName** - `String`
+ **functionVersion** - `String`
+ **initializationType** – ``InitType`` 객체
+ **instanceId?** - `String`
+ **instanceMaxMemory?** - `Integer`
+ **phase** – ``InitPhase`` 객체
+ **runtimeVersion?** – `String`
+ **runtimeVersionArn?** – `String`
다음은 `platform.initStart` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.initStart",
"record": {
"initializationType": "on-demand",
"phase": "init",
"runtimeVersion": "nodejs-14.v3",
"runtimeVersionArn": "arn",
"functionName": "myFunction",
"functionVersion": "$LATEST",
"instanceId": "82561ce0-53dd-47d1-90e0-c8f5e063e62e",
"instanceMaxMemory": 256
}
}
```
### `platform.initRuntimeDone`
`platform.initRuntimeDone` 이벤트는 함수 초기화 단계가 완료되었음을 나타냅니다. `platform.initRuntimeDone` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.initRuntimeDone
- record: PlatformInitRuntimeDone
```
`PlatformInitRuntimeDone` 객체에는 다음 속성이 있습니다.
+ **initializationType** – ``InitType`` 객체
+ **phase** – ``InitPhase`` 객체
+ **status** – ``Status`` 객체
+ **spans?** - ``Span`` 객체의 목록
다음은 `platform.initRuntimeDone` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.initRuntimeDone",
"record": {
"initializationType": "on-demand"
"status": "success",
"spans": [
{
"name": "someTimeSpan",
"start": "2022-06-02T12:02:33.913Z",
"durationMs": 70.5
}
]
}
}
```
### `platform.initReport`
`platform.initReport` 이벤트에는 함수 초기화 단계의 전체 보고서가 포함됩니다. `platform.initReport` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.initReport
- record: PlatformInitReport
```
`PlatformInitReport` 객체에는 다음 속성이 있습니다.
+ **errorType?** - string
+ **initializationType** – ``InitType`` 객체
+ **phase** – ``InitPhase`` 객체
+ **metrics** – ``InitReportMetrics`` 객체
+ **spans?** - ``Span`` 객체의 목록
+ **status** – ``Status`` 객체
다음은 `platform.initReport` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.initReport",
"record": {
"initializationType": "on-demand",
"status": "success",
"phase": "init",
"metrics": {
"durationMs": 125.33
},
"spans": [
{
"name": "someTimeSpan",
"start": "2022-06-02T12:02:33.913Z",
"durationMs": 90.1
}
]
}
}
```
### `platform.start`
`platform.start` 이벤트는 함수 호출 단계가 시작되었음을 나타냅니다. `platform.start` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.start
- record: PlatformStart
```
`PlatformStart` 객체에는 다음 속성이 있습니다.
+ **requestId** – `String`
+ **version?** – `String`
+ **tracing?** – ``TraceContext``
다음은 `platform.start` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.start",
"record": {
"requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa",
"version": "$LATEST",
"tracing": {
"spanId": "54565fb41ac79632",
"type": "X-Amzn-Trace-Id",
"value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1"
}
}
}
```
### `platform.runtimeDone`
`platform.runtimeDone` 이벤트는 함수 호출 단계가 완료되었음을 나타냅니다. `platform.runtimeDone` `Event` 객체의 형식은 다음과 같습니다.
**Lambda 관리형 인스턴스**
Lambda 관리형 인스턴스에서는 `platform.runtimeDone` 이벤트가 지원되지 않습니다. 관리형 인스턴스에서 실행되는 확장은 관리형 인스턴스에서 이벤트를 구독할 수 없으므로 이 `INVOKE` 이벤트를 수신하지 않습니다. 여러 간접 호출을 동시에 처리할 수 있는 동시 실행 모델로 인해 확장은 Lambda(기본값) 함수에서와 같이 개별 간접 호출에 대한 간접 호출 후 처리를 수행할 수 없습니다.
관리형 인스턴스의 경우 일반적으로 `platform.runtimeDone`에 포함된 `responseLatency` 및 `responseDuration` 스팬을 대신 `platform.report` 이벤트에서 사용할 수 있습니다. 세부 정보는 [`platform.report`](#platform-report) 섹션을 참조하세요.
```
Event: Object
- time: String
- type: String = platform.runtimeDone
- record: PlatformRuntimeDone
```
`PlatformRuntimeDone` 객체에는 다음 속성이 있습니다.
+ **errorType?** – `String`
+ **metrics?** – ``RuntimeDoneMetrics`` 객체
+ **requestId** – `String`
+ **status** – ``Status`` 객체
+ **spans?** - ``Span`` 객체의 목록
+ **tracing?** – ``TraceContext`` 객체
다음은 `platform.runtimeDone` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.runtimeDone",
"record": {
"requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa",
"status": "success",
"tracing": {
"spanId": "54565fb41ac79632",
"type": "X-Amzn-Trace-Id",
"value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1"
},
"spans": [
{
"name": "someTimeSpan",
"start": "2022-08-02T12:01:23:521Z",
"durationMs": 80.0
}
],
"metrics": {
"durationMs": 140.0,
"producedBytes": 16
}
}
}
```
### `platform.report`
`platform.report` 이벤트에는 함수 간접 호출 단계의 전체 보고서가 포함됩니다. `platform.report` `Event` 객체의 형식은 다음과 같습니다.
**Lambda 관리형 인스턴스**
Lambda 관리형 인스턴스의 `platform.report` 이벤트는 Lambda(기본값) 함수와 비교하여 지표와 스팬이 다릅니다. 관리형 인스턴스:
**스팬**: `extensionOverhead` 대신 `responseLatency` 및 `responseDuration`을 포함합니다. 동시 실행 모델로 인해 확장이 관리형 인스턴스의 `INVOKE` 이벤트를 구독할 수 없으므로 `extensionOverhead` 스팬을 사용할 수 없습니다.
**지표**: `durationMs`만 포함합니다. `billedDurationMs`, `initDurationMs`, `maxMemoryUsedMB` 및 `memorySizeMB` 지표는 포함되지 않습니다. 이러한 간접 호출당 지표는 동시 실행 환경에 적용할 수 없습니다. 리소스 사용률 지표의 경우 [Lambda 관리형 인스턴스 모니터링](lambda-managed-instances-monitoring.md) 또는 [Lambda Insights](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-insights.html)를 사용합니다.
```
Event: Object
- time: String
- type: String = platform.report
- record: PlatformReport
```
`PlatformReport` 객체에는 다음 속성이 있습니다.
+ **metrics** – ``ReportMetrics`` 객체
+ **requestId** – `String`
+ **spans?** - ``Span`` 객체의 목록
+ **status** – ``Status`` 객체
+ **tracing?** – ``TraceContext`` 객체
다음은 `platform.report` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.report",
"record": {
"metrics": {
"billedDurationMs": 694,
"durationMs": 693.92,
"initDurationMs": 397.68,
"maxMemoryUsedMB": 84,
"memorySizeMB": 128
},
"requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa",
}
}
```
### `platform.restoreStart`
`platform.restoreStart` 이벤트는 함수 환경 복원 이벤트가 시작되었음을 나타냅니다. 환경 복원 이벤트에서 Lambda는 처음부터 초기화하지 않고 캐싱된 스냅샷에서 환경을 생성합니다. 자세한 내용은 [Lambda SnapStart](snapstart.md) 섹션을 참조하세요. `platform.restoreStart` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.restoreStart
- record: PlatformRestoreStart
```
`PlatformRestoreStart` 객체에는 다음 속성이 있습니다.
+ **functionName** - `String`
+ **functionVersion** - `String`
+ **instanceId?** - `String`
+ **instanceMaxMemory?** - `String`
+ **runtimeVersion?** – `String`
+ **runtimeVersionArn?** – `String`
다음은 `platform.restoreStart` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.restoreStart",
"record": {
"runtimeVersion": "nodejs-14.v3",
"runtimeVersionArn": "arn",
"functionName": "myFunction",
"functionVersion": "$LATEST",
"instanceId": "82561ce0-53dd-47d1-90e0-c8f5e063e62e",
"instanceMaxMemory": 256
}
}
```
### `platform.restoreRuntimeDone`
`platform.restoreRuntimeDone` 이벤트는 함수 환경 복원 이벤트가 완료되었음을 나타냅니다. 환경 복원 이벤트에서 Lambda는 처음부터 초기화하지 않고 캐싱된 스냅샷에서 환경을 생성합니다. 자세한 내용은 [Lambda SnapStart](snapstart.md) 섹션을 참조하세요. `platform.restoreRuntimeDone` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.restoreRuntimeDone
- record: PlatformRestoreRuntimeDone
```
`PlatformRestoreRuntimeDone` 객체에는 다음 속성이 있습니다.
+ **errorType?** – `String`
+ **spans?** - ``Span`` 객체의 목록
+ **status** – ``Status`` 객체
다음은 `platform.restoreRuntimeDone` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.restoreRuntimeDone",
"record": {
"status": "success",
"spans": [
{
"name": "someTimeSpan",
"start": "2022-08-02T12:01:23:521Z",
"durationMs": 80.0
}
]
}
}
```
### `platform.restoreReport`
`platform.restoreReport` 이벤트에는 함수 복원 이벤트의 전체 보고서가 포함됩니다. `platform.restoreReport` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.restoreReport
- record: PlatformRestoreReport
```
`PlatformRestoreReport` 객체에는 다음 속성이 있습니다.
+ **errorType?** - string
+ **metrics?** – ``RestoreReportMetrics`` 객체
+ **spans?** - ``Span`` 객체의 목록
+ **status** – ``Status`` 객체
다음은 `platform.restoreReport` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.restoreReport",
"record": {
"status": "success",
"metrics": {
"durationMs": 15.19
},
"spans": [
{
"name": "someTimeSpan",
"start": "2022-08-02T12:01:23:521Z",
"durationMs": 30.0
}
]
}
}
```
### `platform.extension`
`extension` 이벤트에는 확장 코드의 로그가 포함됩니다. `extension` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = extension
- record: {}
```
`PlatformExtension` 객체에는 다음 속성이 있습니다.
+ **events** – `String`의 목록
+ **name** – `String`
+ **state** – `String`
다음은 `platform.extension` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:02:15.000Z",
"type": "platform.extension",
"record": {
"events": [ "INVOKE", "SHUTDOWN" ],
"name": "my-telemetry-extension",
"state": "Ready"
}
}
```
### `platform.telemetrySubscription`
`platform.telemetrySubscription` 이벤트에는 확장 구독에 대한 정보가 포함됩니다. `platform.telemetrySubscription` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.telemetrySubscription
- record: PlatformTelemetrySubscription
```
`PlatformTelemetrySubscription` 객체에는 다음 속성이 있습니다.
+ **name** – `String`
+ **state** – `String`
+ **types** – `String`의 목록
다음은 `platform.telemetrySubscription` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:02:35.000Z",
"type": "platform.telemetrySubscription",
"record": {
"name": "my-telemetry-extension",
"state": "Subscribed",
"types": [ "platform", "function" ]
}
}
```
### `platform.logsDropped`
`platform.logsDropped` 이벤트에는 삭제된 이벤트에 대한 정보가 포함됩니다. 함수의 로그 출력 속도가 높아 Lambda에서 처리할 수 없는 경우에도 Lambda는 `platform.logsDropped` 이벤트를 발생시킵니다. Lambda에서 함수의 로그 생성 속도에 맞춰 CloudWatch 또는 텔레메트리 API가 구독한 확장으로 로그를 전송할 수 없는 경우 로그를 삭제하여 함수 실행 속도가 느려지는 것을 방지합니다. `platform.logsDropped` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = platform.logsDropped
- record: PlatformLogsDropped
```
`PlatformLogsDropped` 객체에는 다음 속성이 있습니다.
+ **droppedBytes** – `Integer`
+ **droppedRecords** – `Integer`
+ **reason** – `String`
다음은 `platform.logsDropped` 유형의 예제 `Event`입니다.
```
{
"time": "2022-10-12T00:02:35.000Z",
"type": "platform.logsDropped",
"record": {
"droppedBytes": 12345,
"droppedRecords": 123,
"reason": "Some logs were dropped because the downstream consumer is slower than the logs production rate"
}
}
```
### `function`
`function` 이벤트에는 함수 코드의 로그가 포함됩니다. `function` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = function
- record: {}
```
`record` 필드 형식은 함수의 로그 형식이 일반 텍스트 형식인지 JSON 형식인지에 따라 달라집니다. 로그 형식 구성 옵션에 대한 자세한 내용은 [JSON 및 일반 텍스트 로그 형식 구성](monitoring-cloudwatchlogs-logformat.md)를 참조하십시오.
다음은 로그 형식이 일반 텍스트인 `Event` 예 `function` 유형입니다.
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "function",
"record": "[INFO] Hello world, I am a function!"
}
```
다음은 로그 형식이 JSON인 `Event` 예 `function` 유형입니다.
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "function",
"record": {
"timestamp": "2022-10-12T00:03:50.000Z",
"level": "INFO",
"requestId": "79b4f56e-95b1-4643-9700-2807f4e68189",
"message": "Hello world, I am a function!"
}
}
```
**참고**
사용 중인 스키마 버전이 `2022-12-13` 버전보다 이전인 경우 함수의 로깅 형식이 JSON으로 구성된 경우에도 `"record"`는 항상 문자열로 렌더링됩니다. Lambda 관리형 인스턴스의 경우 스키마 버전 `2025-01-29`를 사용해야 합니다.
### `extension`
`extension` 이벤트에는 확장 코드의 로그가 포함됩니다. `extension` `Event` 객체의 형식은 다음과 같습니다.
```
Event: Object
- time: String
- type: String = extension
- record: {}
```
`record` 필드 형식은 함수의 로그 형식이 일반 텍스트 형식인지 JSON 형식인지에 따라 달라집니다. 로그 형식 구성 옵션에 대한 자세한 내용은 [JSON 및 일반 텍스트 로그 형식 구성](monitoring-cloudwatchlogs-logformat.md)를 참조하십시오.
다음은 로그 형식이 일반 텍스트인 `Event` 예 `extension` 유형입니다.
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "extension",
"record": "[INFO] Hello world, I am an extension!"
}
```
다음은 로그 형식이 JSON인 `Event` 예 `extension` 유형입니다.
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "extension",
"record": {
"timestamp": "2022-10-12T00:03:50.000Z",
"level": "INFO",
"requestId": "79b4f56e-95b1-4643-9700-2807f4e68189",
"message": "Hello world, I am an extension!"
}
}
```
**참고**
사용 중인 스키마 버전이 `2022-12-13` 버전보다 이전인 경우 함수의 로깅 형식이 JSON으로 구성된 경우에도 `"record"`는 항상 문자열로 렌더링됩니다. Lambda 관리형 인스턴스의 경우 스키마 버전 `2025-01-29`를 사용해야 합니다.
## 공유 객체 유형
이 섹션에서는 Lambda Telemetry API가 지원하는 공유 객체 유형을 자세히 설명합니다.
### `InitPhase`
초기화 작업이 발생하는 단계를 설명하는 문자열 열거형입니다. 대부분의 경우 Lambda는 `init` 단계 중에 함수 초기화 코드를 실행합니다. 하지만 오류가 발생하면 Lambda가 `invoke` 단계 중에 함수 초기화 코드를 다시 실행할 수 있습니다. (이를 *억제된 초기화*라고 함)
+ **유형** – `String`
+ **유효한 값** – `init`\$1`invoke`\$1`snap-start`
### `InitReportMetrics`
초기화 단계에 대한 지표를 포함하는 객체입니다.
+ **유형** – `Object`
`InitReportMetrics` 객체의 형식은 다음과 같습니다.
```
InitReportMetrics: Object
- durationMs: Double
```
다음은 `InitReportMetrics` 객체의 예입니다.
```
{
"durationMs": 247.88
}
```
### `InitType`
Lambda가 환경을 초기화한 방법을 설명하는 문자열 열거형입니다.
+ **유형** – `String`
+ **유효한 값** – `on-demand`\$1`provisioned-concurrency`
### `ReportMetrics`
완료된 단계에 대한 지표가 포함된 객체입니다.
+ **유형** – `Object`
`ReportMetrics` 객체의 형식은 다음과 같습니다.
```
ReportMetrics: Object
- billedDurationMs: Integer
- durationMs: Double
- initDurationMs?: Double
- maxMemoryUsedMB: Integer
- memorySizeMB: Integer
- restoreDurationMs?: Double
```
다음은 `ReportMetrics` 객체의 예입니다.
```
{
"billedDurationMs": 694,
"durationMs": 693.92,
"initDurationMs": 397.68,
"maxMemoryUsedMB": 84,
"memorySizeMB": 128
}
```
### `RestoreReportMetrics`
완료된 복원 단계에 대한 지표가 포함된 객체입니다.
+ **유형** – `Object`
`RestoreReportMetrics` 객체의 형식은 다음과 같습니다.
```
RestoreReportMetrics: Object
- durationMs: Double
```
다음은 `RestoreReportMetrics` 객체의 예입니다.
```
{
"durationMs": 15.19
}
```
### `RuntimeDoneMetrics`
호출 단계에 대한 지표가 포함된 객체입니다.
+ **유형** – `Object`
`RuntimeDoneMetrics` 객체의 형식은 다음과 같습니다.
```
RuntimeDoneMetrics: Object
- durationMs: Double
- producedBytes?: Integer
```
다음은 `RuntimeDoneMetrics` 객체의 예입니다.
```
{
"durationMs": 200.0,
"producedBytes": 15
}
```
### `Span`
범위에 대한 세부 정보가 포함된 객체입니다. 범위는 트레이스의 작업 또는 작업 단위를 나타냅니다. 범위에 대한 자세한 내용은 OpenTelemetry 문서 웹 사이트의 **추적 API** 페이지에서 [범위](https://opentelemetry.io/docs/reference/specification/trace/api/#span)를 참조하세요.
Lambda는 `platform.RuntimeDone` 이벤트에 대해 다음과 같은 범위를 지원합니다.
+ `responseLatency` 범위는 Lambda 함수가 응답의 전송을 시작하는 데 걸린 시간을 나타냅니다.
+ `responseDuration` 범위는 Lambda 함수가 전체 응답의 전송을 마치는 데 걸린 시간을 나타냅니다.
+ `runtimeOverhead` 범위는 Lambda 런타임이 다음 함수 간접 호출을 처리할 준비가 되었음을 알리는 데 걸린 시간을 나타냅니다. 이는 런타임이 함수 응답을 반환한 후 다음 이벤트를 가져오기 위해 [다음 간접 호출](runtimes-api.md#runtimes-api-next) API를 호출하는 데 걸린 시간입니다.
다음은 `responseLatency` 범위 객체의 예입니다.
```
{
"name": "responseLatency",
"start": "2022-08-02T12:01:23.521Z",
"durationMs": 23.02
}
```
### `Status`
초기화 또는 호출 단계의 상태를 설명하는 객체입니다. 상태가 `failure` 또는 `error` 인 경우`Status` 객체에는 오류를 설명하는 `errorType` 필드도 포함됩니다.
+ **유형** – `Object`
+ **유효한 상태 값** – `success`\$1`failure`\$1`error`\$1`timeout`
### `TraceContext`
트레이스의 속성을 설명하는 객체입니다.
+ **유형** – `Object`
`TraceContext` 객체의 형식은 다음과 같습니다.
```
TraceContext: Object
- spanId?: String
- type: TracingType enum
- value: String
```
다음은 `TraceContext` 객체의 예입니다.
```
{
"spanId": "073a49012f3c312e",
"type": "X-Amzn-Trace-Id",
"value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1"
}
```
### `TracingType`
``TraceContext`` 객체의 추적 유형을 설명하는 문자열 열거형입니다.
+ **유형** – `String`
+ **유효한 값** – `X-Amzn-Trace-Id`
# Lambda Telemetry API `Event` 객체를 OpenTelemetry 범위로 변환
AWS Lambda 텔레메트리 API 스키마는 OpenTelemetry(OTel)와 의미 체계가 호환됩니다. 즉, AWS Lambda 텔레메트리 API `Event` 객체를 OpenTelemetry(OTel) 범위로 변환할 수 있습니다. 변환할 때는 단일 `Event` 객체를 단일 OTel 범위에 매핑해서는 안 됩니다. 대신 수명 주기 단계와 관련한 세 가지 이벤트를 모두 단일 OTel 범위에 표시해야 합니다. 예를 들어 `start`, `runtimeDone` 및 `runtimeReport` 이벤트는 단일 함수 호출을 나타냅니다. 이 세 가지 이벤트를 모두 하나의 OTel 범위로 표시합니다.
범위 이벤트 또는 하위(중첩) 범위를 사용하여 이벤트를 변환할 수 있습니다. 이 페이지의 표에서는 두 접근 방식에 대한 텔레메트리 API 스키마 속성과 OTel 범위 속성 간의 매핑을 설명합니다. OTel 범위에 대한 자세한 내용은 OpenTelemetry 문서 웹 사이트의 **추적 API** 페이지에서 [범위](https://opentelemetry.io/docs/reference/specification/trace/api/#span)를 참조하세요.
**Topics**
+ [
## OTel 범위를 범위 이벤트에 매핑
](#telemetry-otel-span-events)
+ [
## OTel 범위를 하위 범위에 매핑
](#telemetry-otel-child-spans)
## OTel 범위를 범위 이벤트에 매핑
다음 표에서 `e`는 텔레메트리 소스에서 발생하는 이벤트를 나타냅니다.
**\$1Start 이벤트 매핑**
| OpenTelemetry | Lambda Telemetry API 스키마 |
| --- | --- |
| `Span.Name` | 확장은 `type` 필드를 기반으로 이 값을 생성합니다. |
| `Span.StartTime` | `e.time`를 사용합니다. |
| `Span.EndTime` | 이벤트가 아직 완료되지 않았으므로 해당 사항이 없습니다. |
| `Span.Kind` | `Server`로 설정합니다. |
| `Span.Status` | `Unset`로 설정합니다. |
| `Span.TraceId` | `e.tracing.value`에 있는 AWS X-Ray 헤더를 구문 분석한 다음 `TraceId` 값을 사용합니다. |
| `Span.ParentId` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Parent` 값을 사용합니다. |
| `Span.SpanId` | 가능한 경우 `e.tracing.spanId`를 사용합니다. 그렇지 않으면 새 `SpanId`를 생성합니다. |
| `Span.SpanContext.TraceState` | X-Ray 트레이스 컨텍스트의 경우 해당 사항이 없습니다. |
| `Span.SpanContext.TraceFlags` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Sampled` 값을 사용합니다. |
| `Span.Attributes` | 확장은 여기에 사용자 지정 값을 추가할 수 있습니다. |
**\$1RuntimeDone 이벤트 매핑**
| OpenTelemetry | Lambda Telemetry API 스키마 |
| --- | --- |
| `Span.Name` | 확장은 `type` 필드를 기반으로 값을 생성합니다. |
| `Span.StartTime` | 일치하는 `*Start` 이벤트의 `e.time`을 사용합니다. 또는 `e.time - e.metrics.durationMs`를 사용합니다. |
| `Span.EndTime` | 이벤트가 아직 완료되지 않았으므로 해당 사항이 없습니다. |
| `Span.Kind` | `Server`로 설정합니다. |
| `Span.Status` | `e.status`가 `success`와 같지 않으면 `Error`로 설정합니다. 그렇지 않으면 `Ok`(으)로 설정합니다. |
| `Span.Events[]` | `e.spans[]`를 사용합니다. |
| `Span.Events[i].Name` | `e.spans[i].name`를 사용합니다. |
| `Span.Events[i].Time` | `e.spans[i].start`를 사용합니다. |
| `Span.TraceId` | `e.tracing.value`에 있는 AWS X-Ray 헤더를 구문 분석한 다음 `TraceId` 값을 사용합니다. |
| `Span.ParentId` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Parent` 값을 사용합니다. |
| `Span.SpanId` | `*Start` 이벤트와 동일한 `SpanId`를 사용합니다. 사용할 수 없는 경우 `e.tracing.spanId`를 사용하거나 새 `SpanId`를 생성합니다. |
| `Span.SpanContext.TraceState` | X-Ray 트레이스 컨텍스트의 경우 해당 사항이 없습니다. |
| `Span.SpanContext.TraceFlags` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Sampled` 값을 사용합니다. |
| `Span.Attributes` | 확장은 여기에 사용자 지정 값을 추가할 수 있습니다. |
**\$1Report 이벤트 매핑**
| OpenTelemetry | Lambda Telemetry API 스키마 |
| --- | --- |
| `Span.Name` | 확장은 `type` 필드를 기반으로 값을 생성합니다. |
| `Span.StartTime` | 일치하는 `*Start` 이벤트의 `e.time`을 사용합니다. 또는 `e.time - e.metrics.durationMs`를 사용합니다. |
| `Span.EndTime` | `e.time`를 사용합니다. |
| `Span.Kind` | `Server`로 설정합니다. |
| `Span.Status` | `*RuntimeDone` 이벤트와 동일한 값을 사용합니다. |
| `Span.TraceId` | `e.tracing.value`에 있는 AWS X-Ray 헤더를 구문 분석한 다음 `TraceId` 값을 사용합니다. |
| `Span.ParentId` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Parent` 값을 사용합니다. |
| `Span.SpanId` | `*Start` 이벤트와 동일한 `SpanId`를 사용합니다. 사용할 수 없는 경우 `e.tracing.spanId`를 사용하거나 새 `SpanId`를 생성합니다. |
| `Span.SpanContext.TraceState` | X-Ray 트레이스 컨텍스트의 경우 해당 사항이 없습니다. |
| `Span.SpanContext.TraceFlags` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Sampled` 값을 사용합니다. |
| `Span.Attributes` | 확장은 여기에 사용자 지정 값을 추가할 수 있습니다. |
## OTel 범위를 하위 범위에 매핑
다음 표에서는 Lambda Telemetry API 이벤트를 `*RuntimeDone` 범위의 하위(중첩) 범위가 포함된 OTel 범위로 변환하는 방법을 설명합니다. `*Start` 및 `*Report` 매핑의 경우 하위 범위와 동일하므로 [OTel 범위를 범위 이벤트에 매핑](#telemetry-otel-span-events)의 테이블을 참조하세요. 이 표에서 `e`는 텔레메트리 소스에서 발생하는 이벤트를 나타냅니다.
**\$1RuntimeDone 이벤트 매핑**
| OpenTelemetry | Lambda Telemetry API 스키마 |
| --- | --- |
| `Span.Name` | 확장은 `type` 필드를 기반으로 값을 생성합니다. |
| `Span.StartTime` | 일치하는 `*Start` 이벤트의 `e.time`을 사용합니다. 또는 `e.time - e.metrics.durationMs`를 사용합니다. |
| `Span.EndTime` | 이벤트가 아직 완료되지 않았으므로 해당 사항이 없습니다. |
| `Span.Kind` | `Server`로 설정합니다. |
| `Span.Status` | `e.status`가 `success`와 같지 않으면 `Error`로 설정합니다. 그렇지 않으면 `Ok`(으)로 설정합니다. |
| `Span.TraceId` | `e.tracing.value`에 있는 AWS X-Ray 헤더를 구문 분석한 다음 `TraceId` 값을 사용합니다. |
| `Span.ParentId` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Parent` 값을 사용합니다. |
| `Span.SpanId` | `*Start` 이벤트와 동일한 `SpanId`를 사용합니다. 사용할 수 없는 경우 `e.tracing.spanId`를 사용하거나 새 `SpanId`를 생성합니다. |
| `Span.SpanContext.TraceState` | X-Ray 트레이스 컨텍스트의 경우 해당 사항이 없습니다. |
| `Span.SpanContext.TraceFlags` | `e.tracing.value`에 있는 X-Ray 헤더를 구문 분석한 다음 `Sampled` 값을 사용합니다. |
| `Span.Attributes` | 확장은 여기에 사용자 지정 값을 추가할 수 있습니다. |
| `ChildSpan[i].Name` | `e.spans[i].name`를 사용합니다. |
| `ChildSpan[i].StartTime` | `e.spans[i].start`를 사용합니다. |
| `ChildSpan[i].EndTime` | `e.spans[i].start + e.spans[i].durations`를 사용합니다. |
| `ChildSpan[i].Kind` | 상위 `Span.Kind`와 동일합니다. |
| `ChildSpan[i].Status` | 상위 `Span.Status`와 동일합니다. |
| `ChildSpan[i].TraceId` | 상위 `Span.TraceId`와 동일합니다. |
| `ChildSpan[i].ParentId` | 상위 `Span.SpanId`를 사용합니다. |
| `ChildSpan[i].SpanId` | 새 `SpanId`를 생성합니다. |
| `ChildSpan[i].SpanContext.TraceState` | X-Ray 트레이스 컨텍스트의 경우 해당 사항이 없습니다. |
| `ChildSpan[i].SpanContext.TraceFlags` | 상위 `Span.SpanContext.TraceFlags`와 동일합니다. |
# Lambda 로그 API 사용
**중요**
Lambda Telemetry API는 Lambda 로그 API를 대체합니다. **로그 API도 계속 정상적으로 작동하지만, 앞으로는 텔레메트리 API만 사용하는 것이 좋습니다.** 텔레메트리 API 또는 로그 API를 사용하여 확장에서 텔레메트리 스트림을 구독할 수 있습니다. 이러한 API 중 하나를 사용하여 구독한 후 다른 API를 사용하여 구독하려고 하면 오류가 반환됩니다.
**Lambda 관리형 인스턴스는 Logs API를 지원하지 않습니다.**
Lambda 관리형 인스턴스는 Logs API를 지원하지 않습니다. 관리형 인스턴스 함수를 사용하는 경우 대신 [텔레메트리 API](telemetry-api.md)를 사용합니다. 텔레메트리 API는 Lambda 함수에서 텔레메트리 데이터를 수집하고 처리할 수 있도록 향상된 기능을 제공합니다.
Lambda는 런타임 로그를 자동으로 캡처하고 Amazon CloudWatch에 스트리밍합니다. 이 로그 스트림에는 함수 코드 및 익스텐션이 생성하는 로그와 함수 호출의 일부로 Lambda가 생성하는 로그가 포함됩니다.
[Lambda 익스텐션](runtimes-extensions-api.md)은 Lambda Runtime Logs API를 사용하여 Lambda [실행 환경](lambda-runtime-environment.md) 내에서 로그 스트림을 구독할 수 있습니다. Lambda가 로그를 익스텐션에 스트리밍하면 익스텐션은 로그를 처리하고 필터링하여 원하는 모든 대상에 전송할 수 있습니다.
![\[\]](http://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/logs-api-concept-diagram.png)
Logs API를 사용하면 익스텐션이 세 가지 다른 로그 스트림을 구독할 수 있습니다.
+ Lambda 함수가 생성하고 `stdout` 또는 `stderr`에 쓰는 함수 로그.
+ 익스텐션 코드가 생성하는 익스텐션 로그.
+ Lambda 플랫폼 로그는 호출 및 익스텐션과 관련된 이벤트 및 오류를 기록합니다.
**참고**
Lambda는 익스텐션이 하나 이상의 로그 스트림을 구독하는 경우에도 모든 로그를 CloudWatch로 전송합니다.
**Topics**
+ [
## 수신 로그 구독
](#runtimes-logs-api-subscribing)
+ [
## 메모리 사용량
](#runtimes-logs-api-memory)
+ [
## 대상 프로토콜
](#runtimes-logs-api-dest)
+ [
## 버퍼링 구성
](#runtimes-logs-api-buffering)
+ [
## 구독 예
](#runtimes-logs-api-subs-example)
+ [
## Logs API용 샘플 코드
](#runtimes-logs-api-samples)
+ [
## Logs API 참조
](#runtimes-logs-api-ref)
+ [
## 로그 메시지
](#runtimes-logs-api-msg)
## 수신 로그 구독
Lambda 익스텐션은 Logs API에 구독 요청을 전송하여 수신 로그를 구독할 수 있습니다.
수신 로그를 구독하려면 익스텐션 식별자(`Lambda-Extension-Identifier`)가 필요합니다. 먼저 [익스텐션을 등록](runtimes-extensions-api.md#extensions-registration-api-a)하여 익스텐션 식별자를 수신합니다. 그런 다음 [초기화](lambda-runtime-environment.md#runtimes-lifecycle-ib)중에 Logs API를 구독합니다. 초기화 단계가 완료되면 Lambda가 구독 요청을 처리하지 않습니다.
**참고**
Logs API 구독은 멱등성이 있습니다. 중복 구독 요청으로 인해 구독이 중복되지 않습니다.
## 메모리 사용량
구독자 수가 증가함에 따라 메모리 사용량이 선형적으로 증가합니다. 각 구독은 새 메모리 버퍼를 열어 로그를 저장하기 때문에 메모리 리소스를 사용합니다. 메모리 사용량을 최적화하기 위해 [버퍼링 구성](#runtimes-logs-api-buffering)을 조정할 수 있습니다. 버퍼 메모리 사용량은 실행 환경의 전체 메모리 소비에 포함됩니다.
## 대상 프로토콜
다음 프로토콜 중 하나를 선택하여 로그를 수신할 수 있습니다.
1. **HTTP**(권장) - Lambda가 로그를 로컬 HTTP 엔드포인트(`http://sandbox.localdomain:${PORT}/${PATH}`)에 JSON 형식의 레코드 배열로 전달합니다. `$PATH` 파라미터는 선택 항목입니다. HTTPS가 아닌 HTTP만 지원됩니다. PUT 또는 POST를 통해 로그를 수신하도록 선택할 수 있습니다.
1. **TCP** – Lambda가 로그를 [새 줄 구분 JSON(NDJSON) 형식](https://github.com/ndjson/ndjson-spec)으로 TCP 포트에 전달합니다.
TCP 대신 HTTP를 사용하는 것이 좋습니다. TCP를 사용하면 Lambda 플랫폼에서는 로그를 애플리케이션 계층에 전송할 때 인식할 수 없습니다. 따라서 익스텐션이 충돌하는 경우 로그가 손실될 수 있습니다. HTTP에는 이러한 제한이 없습니다.
또한 수신 로그를 구독하기 전에 로컬 HTTP 수신기 또는 TCP 포트를 설정하는 것이 좋습니다. 설치하는 동안 다음 사항에 유의하세요.
+ Lambda는 실행 환경 내에 있는 대상에만 로그를 보냅니다.
+ Lambda는 리스너가 없거나 POST 또는 PUT 요청으로 인해 오류가 발생하는 경우 로그 전송을 다시 시도합니다(백오프 포함). 로그 구독자가 충돌하면 Lambda가 실행 환경을 다시 시작한 후 로그를 계속 수신합니다.
+ Lambda는 포트 9001을 예약합니다. 다른 포트 번호 제한이나 권장 사항은 없습니다.
## 버퍼링 구성
Lambda는 로그를 버퍼링하여 구독자에게 전달할 수 있습니다. 다음과 같은 선택적 필드를 지정하여 구독 요청에서 이 동작을 구성할 수 있습니다. Lambda는 지정하지 않은 필드에 기본값을 사용합니다.
+ **timeoutMs** – 배치를 버퍼링할 최대 시간(밀리초)입니다. 기본값: 1,000. 최소: 25 최대값: 30,000.
+ **maxBytes** – 메모리에 버퍼링할 로그의 최대 크기(바이트)입니다. 기본값: 262,144. 최소값: 262,144. 최대값: 1,048,576.
+ **maxItems** – 메모리에 버퍼링할 최대 이벤트 수입니다. 기본값: 10,000. 최소값: 1,000. 최대값: 10,000.
버퍼링 구성 중에 다음 사항에 유의하세요.
+ Lambda는 런타임 충돌 등으로 인해 입력 스트림이 닫히면 로그를 플러시합니다.
+ 각 구독자는 구독 요청에서 다른 버퍼링 구성을 지정할 수 있습니다.
+ 데이터를 읽는 데 필요한 버퍼 크기를 고려하세요. 최대 `2*maxBytes+metadata` 크기의 페이로드를 수신할 수 있도록 준비하세요. 여기서, `maxBytes`는 구독 요청에서 구성됩니다. 예를 들어 Lambda는 각 레코드에 다음 메타데이터 바이트를 추가합니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}
```
+ 구독자가 들어오는 로그를 충분히 빠르게 처리할 수 없는 경우 Lambda는 메모리 사용률을 범위 내로 유지하기 위해 로그를 삭제할 수 있습니다. 삭제된 레코드의 수를 나타내기 위해 Lambda는 `platform.logsDropped` 로그를 전송합니다. 자세한 내용은 [Lambda: 일부 함수 로그가 표시되지 않음](troubleshooting-execution.md#troubleshooting-execution-missinglogs) 섹션을 참조하세요.
## 구독 예
다음 예제에서는 플랫폼 및 함수 로그를 구독하는 요청을 보여줍니다.
```
PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs HTTP/1.1
{ "schemaVersion": "2020-08-15",
"types": [
"platform",
"function"
],
"buffering": {
"maxItems": 1000,
"maxBytes": 262144,
"timeoutMs": 100
},
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080/lambda_logs"
}
}
```
요청이 성공하면 구독자는 HTTP 200 성공 응답을 받습니다.
```
HTTP/1.1 200 OK
"OK"
```
## Logs API용 샘플 코드
로그를 사용자 지정 대상으로 보내는 방법을 보여 주는 샘플 코드는 AWS Lambda 컴퓨팅 블로그의 [AWS 익스텐션을 사용하여 사용자 지정 대상으로 로그 전송](https://aws.amazon.com/blogs/compute/using-aws-lambda-extensions-to-send-logs-to-custom-destinations/)을 참조하세요.
기본 Lambda 익스텐션을 개발하고 Logs API를 구독하는 방법을 보여주는 Python 및 Go 코드 예제는 AWS 샘플 GitHub 리포지토리의 [AWS Lambda 익스텐션](https://github.com/aws-samples/aws-lambda-extensions)을 참조하세요. Lambda 익스텐션 빌드에 대한 자세한 내용은 [Lambda 확장 API를 사용하여 확장 생성](runtimes-extensions-api.md) 단원을 참조하세요.
## Logs API 참조
`AWS_LAMBDA_RUNTIME_API` 환경 변수에서 Logs API 엔드포인트를 검색할 수 있습니다. API 요청을 보내려면 API 경로 앞에 `2020-08-15/` 접두사를 사용합니다. 예:
```
http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs
```
로그 API 버전 **2020-08-15**에 대한 OpenAPI 사양은 여기에서 사용할 수 있습니다. [logs-api-request.zip](samples/logs-api-request.zip)
### Subscribe
Lambda 실행 환경에서 사용할 수 있는 하나 이상의 로그 스트림을 구독하기 위해 익스텐션이 Subscribe API 요청을 전송합니다.
**경로** – `/logs`
**메서드** – **PUT**
**본문 파라미터**
`destination` 단원을 참조하세요.[대상 프로토콜](#runtimes-logs-api-dest) 필수 항목 여부: 예. 유형: 문자열.
`buffering` 단원을 참조하세요.[버퍼링 구성](#runtimes-logs-api-buffering) 필수 항목 여부: 아니요 유형: 문자열.
`types` – 수신할 로그 유형의 배열입니다. 필수 항목 여부: 예. 유형: 문자열 배열 유효한 값: "platform", "function", "extension".
`schemaVersion` – 필수 항목 여부: 아니요 기본값: "2020-08-15". 익스텐션에서 [`platform.runtimeDone`](#runtimes-logs-api-ref-done) 메시지를 수신하려면 ‘2021-03-18’으로 설정합니다.
****응답 파라미터****
구독 응답에 대한 OpenAPI 사양(버전 **2020-08-15**)은 HTTP 및 TCP 프로토콜에 사용할 수 있습니다.
+ HTTP: [logs-api-http-response.zip](samples/logs-api-http-response.zip)
+ TCP: [logs-api-tcp-response.zip](samples/logs-api-tcp-response.zip)
****응답 코드****
+ 200 - 요청이 성공적으로 완료되었습니다.
+ 202 - 요청이 수락되었습니다. 로컬 테스트 중 구독 요청에 대한 응답입니다.
+ 4XX - 잘못된 요청
+ 500 - 서비스 오류
요청이 성공하면 구독자는 HTTP 200 성공 응답을 받습니다.
```
HTTP/1.1 200 OK
"OK"
```
요청이 실패하면 구독자는 오류 응답을 받습니다. 예:
```
HTTP/1.1 400 OK
{
"errorType": "Logs.ValidationError",
"errorMessage": URI port is not provided; types should not be empty"
}
```
## 로그 메시지
Logs API를 사용하면 익스텐션이 세 가지 다른 로그 스트림을 구독할 수 있습니다.
+ Function – Lambda 함수가 생성하고 `stdout` 또는 `stderr`에 쓰는 함수 로그.
+ 익스텐션 - 익스텐션 코드가 생성하는 로그.
+ 플랫폼 - 런타임 플랫폼이 생성하는 로그로 호출 및 익스텐션과 관련된 이벤트 및 오류 기록.
**Topics**
+ [
### 함수 로그
](#runtimes-logs-api-msg-function)
+ [
### 익스텐션 로그
](#runtimes-logs-api-msg-extension)
+ [
### 플랫폼 로그
](#runtimes-logs-api-msg-platform)
### 함수 로그
Lambda 함수 및 내부 익스텐션은 함수 로그를 생성하여 `stdout` 또는 `stderr`에 작성합니다.
다음 예에서는 함수 로그 메시지의 형식을 보여 줍니다.\$1 "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\$1n\$1my-function (line 10)\$1n" \$1
### 익스텐션 로그
익스텐션은 익스텐션 로그를 생성할 수 있습니다. 로그 형식은 함수 로그와 같습니다.
### 플랫폼 로그
Lambda는 `platform.start`, `platform.end`, `platform.fault`와 같은 플랫폼 이벤트에 대한 로그 메시지를 생성합니다
또는 `platform.runtimeDone` 로그 메시지를 포함하는 로그 API 스키마의 **2021-03-18** 버전을 구독할 수 있습니다.
#### 플랫폼 로그 메시지 예
다음 예에서는 플랫폼 시작 로그와 플랫폼 종료 로그를 보여 줍니다. 이러한 로그는 requestID가 지정하는 호출에 대한 호출 시작 시간 및 호출 종료 시간을 나타냅니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.start",
"record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}
}
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.end",
"record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}
}
```
**platform.initRuntimeDone** 로그 메시지는 [Init 수명 주기 단계](lambda-runtime-environment.md#runtimes-lifecycle-ib)의 일부인 `Runtime init` 하위 단계의 상태를 보여줍니다. `Runtime init`가 성공하면 런타임이 `/next` 런타임 API 요청(`on-demand` 및 `provisioned-concurrency` 초기화 유형의 경우) 또는 `restore/next`(`snap-start` 초기화 유형의 경우)를 전송합니다. 다음 예에서는 `snap-start` 초기화 유형에 대한 성공적인 **platform.initRuntimeDone** 로그 메시지를 보여줍니다.
```
{
"time":"2022-07-17T18:41:57.083Z",
"type":"platform.initRuntimeDone",
"record":{
"initializationType":"snap-start",
"status":"success"
}
}
```
**platform.initReport** 로그 메시지에는 `Init` 단계가 지속된 시간과 이 단계에서 청구된 시간(밀리초)이 표시됩니다. 초기화 유형이 `provisioned-concurrency`인 경우 Lambda는 호출 중에 이 메시지를 보냅니다. 초기화 유형이 `snap-start`인 경우 Lambda는 스냅샷을 복원한 후에 이 메시지를 보냅니다. 다음 예에서는 `snap-start` 초기화 유형에 대한 **platform.initReport** 로그 메시지를 보여줍니다.
```
{
"time":"2022-07-17T18:41:57.083Z",
"type":"platform.initReport",
"record":{
"initializationType":"snap-start",
"metrics":{
"durationMs":731.79,
"billedDurationMs":732
}
}
}
```
플랫폼 보고서 로그에는 requestId가 지정하는 호출에 대한 지표가 포함됩니다. 이 `initDurationMs` 필드는 호출에 콜드 스타트가 포함된 경우에만 로그에 포함됩니다. AWS X-Ray 추적이 활성 상태인 경우 로그에 X-Ray 메타데이터가 포함됩니다. 다음 예에서는 콜드 스타트를 포함한 호출에 대한 플랫폼 보고서 로그를 보여 줍니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.report",
"record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56",
"metrics": {"durationMs": 101.51,
"billedDurationMs": 300,
"memorySizeMB": 512,
"maxMemoryUsedMB": 33,
"initDurationMs": 116.67
}
}
}
```
플랫폼 오류 로그는 런타임 또는 실행 환경 오류를 캡처합니다. 다음 예제에서는 플랫폼 장애 로그 메시지를 보여줍니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.fault",
"record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before completing request"
}
```
**참고**
AWS는 현재 Lambda 서비스에 대한 변경 사항을 구현하고 있습니다. 이러한 변경으로 인해, AWS 계정의 여러 Lambda 함수에서 내보내는 시스템 로그 메시지와 추적 세그먼트의 구조와 내용 간에 약간의 차이가 있을 수 있습니다.
이 변경의 영향을 받는 로그 출력 중 하나는 플랫폼 장애 로그 `"record"` 필드입니다. 다음 예는 이전 형식과 새 형식의 `"record"` 필드를 보여줍니다. 새 스타일의 장애 로그에는 더 간결한 메시지가 포함됩니다.
이러한 변경 사항은 앞으로 몇 주 동안 구현되며, 중국 및 GovCloud 리전을 제외한 모든 AWS 리전의 모든 기능은 새로운 형식의 로그 메시지 및 추적 세그먼트를 사용하도록 전환됩니다.
**Example 플랫폼 장애 로그 레코드(이전 스타일)**
```
"record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError"
```
**Example 플랫폼 장애 로그 레코드(새 스타일)**
```
"record":"RequestId: ... Status: error\tErrorType: Runtime.ExitError"
```
Lambda는 익스텐션이 익스텐션 API에 등록할 때 플랫폼 익스텐션 로그를 생성합니다. 다음 예에서는 플랫폼 익스텐션 메시지를 보여줍니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.extension",
"record": {"name": "Foo.bar",
"state": "Ready",
"events": ["INVOKE", "SHUTDOWN"]
}
}
```
Lambda는 익스텐션이 로그 API를 구독할 때 플랫폼 로그 구독 로그를 생성합니다. 다음 예는 로그 구독 로그 메시지를 보여줍니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.logsSubscription",
"record": {"name": "Foo.bar",
"state": "Subscribed",
"types": ["function", "platform"],
}
}
```
Lambda는 익스텐션이 수신 중인 로그 수를 처리할 수 없는 경우 플랫폼 로그 삭제 로그를 생성합니다. 다음 예제에서는 `platform.logsDropped` 로그 메시지를 보여줍니다.
```
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.logsDropped",
"record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged receipt of logs.",
"droppedRecords": 123,
"droppedBytes" 12345
}
}
```
**platform.restoreStart** 로그 메시지에는 `Restore` 단계가 시작된 시간이 표시됩니다(`snap-start` 초기화 유형만 해당). 예제:
```
{
"time":"2022-07-17T18:43:44.782Z",
"type":"platform.restoreStart",
"record":{}
}
```
**platform.restoreReport** 로그 메시지에는 `Restore` 단계가 지속된 시간과 이 단계에서 청구된 시간(밀리초)이 표시됩니다(`snap-start` 초기화 유형만 해당). 예제:
```
{
"time":"2022-07-17T18:43:45.936Z",
"type":"platform.restoreReport",
"record":{
"metrics":{
"durationMs":70.87,
"billedDurationMs":13
}
}
}
```
#### 플랫폼 `runtimeDone` 메시지
구독 요청에서 스키마 버전을 ‘2021-03-18’로 설정하면 Lambda는 함수 호출이 성공적으로 완료되거나 오류가 발생한 경우 `platform.runtimeDone` 메시지를 보냅니다. 익스텐션은 이 메시지를 사용하여 이 함수 호출에 대한 모든 원격 분석 수집을 중지할 수 있습니다.
스키마 버전 **2021-03-18**의 로그 이벤트 유형에 대한 OpenAPI 사양은 [schema-2021-03-18.zip](samples/schema-2021-03-18.zip)에서 사용할 수 있습니다.
Lambda는 런타임에서 `Next` 또는 `Error` 런타임 API 요청을 보낼 때 `platform.runtimeDone` 로그 메시지를 생성합니다. `platform.runtimeDone` 로그는 함수 호출이 완료되었음을 로그 API 사용자에게 알립니다. 익스텐션은 이 정보를 사용하여 해당 호출 중에 수집된 모든 원격 분석을 보낼 시간을 결정할 수 있습니다.
##### 예제
Lambda는 함수 호출이 완료되면 런타임에서 NEXT 요청을 보낸 후 `platform.runtimeDone` 메시지를 전송합니다. 다음 예에서는 각 상태 값에 대한 메시지(성공, 실패 및 시간 초과)를 보여줍니다.
**Example 성공 메시지 예**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "success"
}
}
```
**Example 오류 메시지 예**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "failure"
}
}
```
**Example 시간 초과 메시지 예**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "timeout"
}
}
```
**Example platform.restoreRuntimeDone 메시지의 예(`snap-start` 초기화 유형만 해당)**
**platform.restoreRuntimeDone** 로그 메시지는 `Restore` 단계의 성공 여부를 표시합니다. Lambda는 런타임이 `restore/next` 런타임 API 요청을 보낼 때 이 로그 메시지를 보냅니다. 가능한 상태로는 성공, 실패 및 시간 초과가 있습니다. 다음 예는 성공적인 **platform.restoreRuntimeDone** 로그 메시지를 보여줍니다.
```
{
"time":"2022-07-17T18:43:45.936Z",
"type":"platform.restoreRuntimeDone",
"record":{
"status":"success"
}
}
```