# 텔레메트리 API를 사용하여 확장의 실시간 텔레메트리 데이터에 액세스
<a name="telemetry-api"></a>

텔레메트리 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를 사용하여 확장 생성
<a name="telemetry-api-creating-extensions"></a>

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` 수명 주기 이벤트를 사용하여 각 배치를 원하는 대상으로 전송합니다.

## 확장 등록
<a name="telemetry-api-registration"></a>

텔레메트리 데이터를 구독하려면 먼저 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)을 참조하세요.

## 텔레메트리 리스너 생성
<a name="telemetry-api-listener"></a>

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
}
```

## 대상 프로토콜 지정
<a name="telemetry-api-destination"></a>

텔레메트리를 수신하기 위해 텔레메트리 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을 예약합니다. 다른 포트 번호 제한이나 권장 사항은 없습니다.

## 메모리 사용량 및 버퍼링 구성
<a name="telemetry-api-buffering"></a>

실행 환경에서 메모리 사용량은 구독자 수에 따라 선형적으로 증가합니다. 각 구독은 새 메모리 버퍼를 열어 텔레메트리 데이터를 저장하기 때문에 메모리 리소스를 사용합니다. 버퍼 메모리 사용량은 실행 환경의 전체 메모리 소비에 포함됩니다.

텔레메트리 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에 구독 요청 전송
<a name="telemetry-api-subscription"></a>

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 메시지
<a name="telemetry-api-messages"></a>

텔레메트리 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 참조
<a name="telemetry-api-reference"></a>

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)

## 구독
<a name="telemetry-subscribe-api"></a>

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 요청의 예
<a name="telemetry-subscribe-api-example"></a>

```
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` 스키마 참조
<a name="telemetry-schema-reference"></a>

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` 객체 유형
<a name="telemetry-api-events"></a>

이 섹션에서는 Lambda Telemetry API가 지원하는 `Event` 객체 유형을 자세히 설명합니다. 이벤트 설명에서 물음표(`?`)는 해당 속성이 객체에 없을 수 있음을 나타냅니다.

### `platform.initStart`
<a name="platform-initStart"></a>

`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`
<a name="platform-initRuntimeDone"></a>

`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`
<a name="platform-initReport"></a>

`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`
<a name="platform-start"></a>

`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`
<a name="platform-runtimeDone"></a>

`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`
<a name="platform-report"></a>

`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`
<a name="platform-restoreStart"></a>

`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`
<a name="platform-restoreRuntimeDone"></a>

`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`
<a name="platform-restoreReport"></a>

`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`
<a name="platform-extension"></a>

`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`
<a name="platform-telemetrySubscription"></a>

`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`
<a name="platform-logsDropped"></a>

`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`
<a name="telemetry-api-function"></a>

`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`
<a name="telemetry-api-extension"></a>

`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`를 사용해야 합니다.

## 공유 객체 유형
<a name="telemetry-api-objects"></a>

이 섹션에서는 Lambda Telemetry API가 지원하는 공유 객체 유형을 자세히 설명합니다.

### `InitPhase`
<a name="InitPhase"></a>

초기화 작업이 발생하는 단계를 설명하는 문자열 열거형입니다. 대부분의 경우 Lambda는 `init` 단계 중에 함수 초기화 코드를 실행합니다. 하지만 오류가 발생하면 Lambda가 `invoke` 단계 중에 함수 초기화 코드를 다시 실행할 수 있습니다. (이를 *억제된 초기화*라고 함)
+ **유형** – `String`
+ **유효한 값** – `init`\$1`invoke`\$1`snap-start`

### `InitReportMetrics`
<a name="InitReportMetrics"></a>

초기화 단계에 대한 지표를 포함하는 객체입니다.
+ **유형** – `Object`

`InitReportMetrics` 객체의 형식은 다음과 같습니다.

```
InitReportMetrics: Object
- durationMs: Double
```

다음은 `InitReportMetrics` 객체의 예입니다.

```
{
    "durationMs": 247.88
}
```

### `InitType`
<a name="InitType"></a>

Lambda가 환경을 초기화한 방법을 설명하는 문자열 열거형입니다.
+ **유형** – `String`
+ **유효한 값** – `on-demand`\$1`provisioned-concurrency`

### `ReportMetrics`
<a name="ReportMetrics"></a>

완료된 단계에 대한 지표가 포함된 객체입니다.
+ **유형** – `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`
<a name="RestoreReportMetrics"></a>

완료된 복원 단계에 대한 지표가 포함된 객체입니다.
+ **유형** – `Object`

`RestoreReportMetrics` 객체의 형식은 다음과 같습니다.

```
RestoreReportMetrics: Object
- durationMs: Double
```

다음은 `RestoreReportMetrics` 객체의 예입니다.

```
{
    "durationMs": 15.19
}
```

### `RuntimeDoneMetrics`
<a name="RuntimeDoneMetrics"></a>

호출 단계에 대한 지표가 포함된 객체입니다.
+ **유형** – `Object`

`RuntimeDoneMetrics` 객체의 형식은 다음과 같습니다.

```
RuntimeDoneMetrics: Object
- durationMs: Double
- producedBytes?: Integer
```

다음은 `RuntimeDoneMetrics` 객체의 예입니다.

```
{
    "durationMs": 200.0,
    "producedBytes": 15
}
```

### `Span`
<a name="Span"></a>

범위에 대한 세부 정보가 포함된 객체입니다. 범위는 트레이스의 작업 또는 작업 단위를 나타냅니다. 범위에 대한 자세한 내용은 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`
<a name="Status"></a>

초기화 또는 호출 단계의 상태를 설명하는 객체입니다. 상태가 `failure` 또는 `error` 인 경우`Status` 객체에는 오류를 설명하는 `errorType` 필드도 포함됩니다.
+ **유형** – `Object`
+ **유효한 상태 값** – `success`\$1`failure`\$1`error`\$1`timeout`

### `TraceContext`
<a name="TraceContext"></a>

트레이스의 속성을 설명하는 객체입니다.
+ **유형** – `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`
<a name="TracingType"></a>

``TraceContext`` 객체의 추적 유형을 설명하는 문자열 열거형입니다.
+ **유형** – `String`
+ **유효한 값** – `X-Amzn-Trace-Id`

# Lambda Telemetry API `Event` 객체를 OpenTelemetry 범위로 변환
<a name="telemetry-otel-spans"></a>

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 범위를 범위 이벤트에 매핑
<a name="telemetry-otel-span-events"></a>

다음 표에서 `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 범위를 하위 범위에 매핑
<a name="telemetry-otel-child-spans"></a>

다음 표에서는 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 사용
<a name="runtimes-logs-api"></a>

**중요**  
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)

## 수신 로그 구독
<a name="runtimes-logs-api-subscribing"></a>

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 구독은 멱등성이 있습니다. 중복 구독 요청으로 인해 구독이 중복되지 않습니다.

## 메모리 사용량
<a name="runtimes-logs-api-memory"></a>

구독자 수가 증가함에 따라 메모리 사용량이 선형적으로 증가합니다. 각 구독은 새 메모리 버퍼를 열어 로그를 저장하기 때문에 메모리 리소스를 사용합니다. 메모리 사용량을 최적화하기 위해 [버퍼링 구성](#runtimes-logs-api-buffering)을 조정할 수 있습니다. 버퍼 메모리 사용량은 실행 환경의 전체 메모리 소비에 포함됩니다.

## 대상 프로토콜
<a name="runtimes-logs-api-dest"></a>

다음 프로토콜 중 하나를 선택하여 로그를 수신할 수 있습니다.

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을 예약합니다. 다른 포트 번호 제한이나 권장 사항은 없습니다.

## 버퍼링 구성
<a name="runtimes-logs-api-buffering"></a>

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) 섹션을 참조하세요.

## 구독 예
<a name="runtimes-logs-api-subs-example"></a>

다음 예제에서는 플랫폼 및 함수 로그를 구독하는 요청을 보여줍니다.

```
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용 샘플 코드
<a name="runtimes-logs-api-samples"></a>

로그를 사용자 지정 대상으로 보내는 방법을 보여 주는 샘플 코드는 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 참조
<a name="runtimes-logs-api-ref"></a>

`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
<a name="runtimes-logs-api-ref-a"></a>

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"
}
```

## 로그 메시지
<a name="runtimes-logs-api-msg"></a>

Logs API를 사용하면 익스텐션이 세 가지 다른 로그 스트림을 구독할 수 있습니다.
+ Function – Lambda 함수가 생성하고 `stdout` 또는 `stderr`에 쓰는 함수 로그.
+ 익스텐션 - 익스텐션 코드가 생성하는 로그.
+ 플랫폼 - 런타임 플랫폼이 생성하는 로그로 호출 및 익스텐션과 관련된 이벤트 및 오류 기록.

**Topics**
+ [

### 함수 로그
](#runtimes-logs-api-msg-function)
+ [

### 익스텐션 로그
](#runtimes-logs-api-msg-extension)
+ [

### 플랫폼 로그
](#runtimes-logs-api-msg-platform)

### 함수 로그
<a name="runtimes-logs-api-msg-function"></a>

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 

### 익스텐션 로그
<a name="runtimes-logs-api-msg-extension"></a>

익스텐션은 익스텐션 로그를 생성할 수 있습니다. 로그 형식은 함수 로그와 같습니다.

### 플랫폼 로그
<a name="runtimes-logs-api-msg-platform"></a>

Lambda는 `platform.start`, `platform.end`, `platform.fault`와 같은 플랫폼 이벤트에 대한 로그 메시지를 생성합니다

또는 `platform.runtimeDone` 로그 메시지를 포함하는 로그 API 스키마의 **2021-03-18** 버전을 구독할 수 있습니다.

#### 플랫폼 로그 메시지 예
<a name="runtimes-logs-api-examples"></a>

다음 예에서는 플랫폼 시작 로그와 플랫폼 종료 로그를 보여 줍니다. 이러한 로그는 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` 메시지
<a name="runtimes-logs-api-ref-done"></a>

구독 요청에서 스키마 버전을 ‘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 사용자에게 알립니다. 익스텐션은 이 정보를 사용하여 해당 호출 중에 수집된 모든 원격 분석을 보낼 시간을 결정할 수 있습니다.

##### 예제
<a name="runtimes-logs-api-examples"></a>

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"
  }
}
```