# 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 - 서비스 오류