수신 로그 구독 메모리 사용량 대상 프로토콜 버퍼링 구성 구독 예 Logs API용 샘플 코드 Logs API 참조 로그 메시지

Lambda 로그 API

중요

Lambda 텔레메트리 API는 Lambda 로그 API를 대체합니다. 로그 API도 계속 정상적으로 작동하지만, 앞으로는 텔레메트리 API만 사용하는 것이 좋습니다. 텔레메트리 API 또는 로그 API를 사용하여 확장에서 텔레메트리 스트림을 구독할 수 있습니다. 이러한 API 중 하나를 사용하여 구독한 후 다른 API를 사용하여 구독하려고 하면 오류가 반환됩니다.

Lambda는 런타임 로그를 자동으로 캡처하여 Amazon으로 스트리밍합니다. CloudWatch 이 로그 스트림에는 함수 코드 및 익스텐션이 생성하는 로그와 함수 호출의 일부로 Lambda가 생성하는 로그가 포함됩니다.

Lambda 익스텐션은 Lambda Runtime Logs API를 사용하여 Lambda 실행 환경 내에서 로그 스트림을 구독할 수 있습니다. Lambda가 로그를 익스텐션에 스트리밍하면 익스텐션은 로그를 처리하고 필터링하여 원하는 모든 대상에 전송할 수 있습니다.

Extensions API 및 Logs API는 Lambda와 외부 익스텐션을 연결합니다.

Logs API를 사용하면 익스텐션이 세 가지 다른 로그 스트림을 구독할 수 있습니다.

Lambda 함수가 생성하고 stdout 또는 stderr에 쓰는 함수 로그.
익스텐션 코드가 생성하는 익스텐션 로그.
Lambda 플랫폼 로그는 호출 및 익스텐션과 관련된 이벤트 및 오류를 기록합니다.

참고

확장 프로그램이 하나 이상의 로그 스트림을 CloudWatch 구독하는 경우에도 Lambda는 모든 로그를 로 전송합니다.

수신 로그 구독

Lambda 익스텐션은 Logs API에 구독 요청을 전송하여 수신 로그를 구독할 수 있습니다.

수신 로그를 구독하려면 익스텐션 식별자(Lambda-Extension-Identifier)가 필요합니다. 먼저 익스텐션을 등록하여 익스텐션 식별자를 수신합니다. 그런 다음 초기화중에 Logs API를 구독합니다. 초기화 단계가 완료되면 Lambda가 구독 요청을 처리하지 않습니다.

참고

Logs API 구독은 멱등성이 있습니다. 중복 구독 요청으로 인해 구독이 중복되지 않습니다.

메모리 사용량

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

대상 프로토콜

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

HTTP(권장) - Lambda가 로그를 로컬 HTTP 엔드포인트(http://sandbox.localdomain:${PORT}/${PATH})에 JSON 형식의 레코드 배열로 전달합니다. $PATH 파라미터는 선택 항목입니다. HTTPS가 아닌 HTTP만 지원됩니다. PUT 또는 POST를 통해 로그를 수신하도록 선택할 수 있습니다.
TCP – Lambda가 로그를 새 줄 구분 JSON(NDJSON) 형식으로 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 로그를 전송합니다.

구독 예

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


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 익스텐션을 사용하여 사용자 지정 대상으로 로그 전송을 참조하세요.

기본 Lambda 확장 프로그램을 개발하고 Logs API를 구독하는 방법을 보여주는 Python 및 Go 코드 예제는 샘플 리포지토리의 확장 프로그램을 AWS Lambda참조하십시오. AWS GitHub Lambda 익스텐션 빌드에 대한 자세한 내용은 Lambda 익스텐션 API 단원을 참조하세요.

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 사양은 다음에서 확인할 수 있습니다.zip logs-api-request

Lambda 실행 환경에서 사용할 수 있는 하나 이상의 로그 스트림을 구독하기 위해 익스텐션이 Subscribe API 요청을 전송합니다.

경로 – /logs

메서드 – PUT

본문 파라미터

destination 단원을 참조하세요.대상 프로토콜 필수 항목 여부: 예. 유형: 문자열.

buffering 단원을 참조하세요.버퍼링 구성 필수 항목 여부: 아니요 유형: 문자열.

types – 수신할 로그 유형의 배열입니다. 필수 항목 여부: 예. 유형: 문자열 배열 유효한 값: "platform", "function", "extension".

schemaVersion – 필수 항목 여부: 아니요 기본값: "2020-08-15". 익스텐션에서 platform.runtimeDone 메시지를 수신하려면 ‘2021-03-18’으로 설정합니다.

응답 파라미터

구독 응답에 대한 OpenAPI 사양(버전 2020-08-15)은 HTTP 및 TCP 프로토콜에 사용할 수 있습니다.

응답 코드

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에 쓰는 함수 로그.
익스텐션 - 익스텐션 코드가 생성하는 로그.
플랫폼 - 런타임 플랫폼이 생성하는 로그로 호출 및 익스텐션과 관련된 이벤트 및 오류 기록.

주제

함수 로그
익스텐션 로그
플랫폼 로그

함수 로그

Lambda 함수 및 내부 익스텐션은 함수 로그를 생성하여 stdout 또는 stderr에 작성합니다.

다음 예에서는 함수 로그 메시지의 형식을 보여 줍니다.{ "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\n\my-function (line 10)\n" }

익스텐션 로그

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

플랫폼 로그

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

플랫폼. initRuntimeDone로그 메시지는 Init 라이프사이클 Runtime init 단계의 일부인 하위 단계의 상태를 보여줍니다. Runtime init가 성공하면 런타임이 /next 런타임 API 요청(on-demand 및 provisioned-concurrency 초기화 유형의 경우) 또는 restore/next(snap-start 초기화 유형의 경우)를 전송합니다. 다음 예제는 성공적인 플랫폼을 보여줍니다. initRuntimeDonesnap-start초기화 유형에 대한 로그 메시지.


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

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에서 사용할 수 있습니다.

Lambda는 런타임에서 Next 또는 Error 런타임 API 요청을 보낼 때 platform.runtimeDone 로그 메시지를 생성합니다. platform.runtimeDone 로그는 함수 호출이 완료되었음을 로그 API 사용자에게 알립니다. 익스텐션은 이 정보를 사용하여 해당 호출 중에 수집된 모든 원격 분석을 보낼 시간을 결정할 수 있습니다.

예제

Lambda는 함수 호출이 완료되면 런타임에서 NEXT 요청을 보낸 후 platform.runtimeDone 메시지를 전송합니다. 다음 예에서는 각 상태 값에 대한 메시지(성공, 실패 및 시간 초과)를 보여줍니다.

예 성공 메시지 예


{
    "time": "2021-02-04T20:00:05.123Z",
    "type": "platform.runtimeDone",
    "record": {
       "requestId":"6f7f0961f83442118a7af6fe80b88",
       "status": "success"
    }
}

예 오류 메시지 예


{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "failure"
   }
}

예 시간 초과 메시지 예


{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "timeout"
  }
}

예제 플랫폼. restoreRuntimeDone 메시지 (`snap-start`초기화 유형만 해당)

플랫폼. restoreRuntimeDone로그 메시지에는 Restore 단계가 성공했는지 여부가 표시됩니다. Lambda는 런타임이 restore/next 런타임 API 요청을 보낼 때 이 로그 메시지를 보냅니다. 가능한 상태로는 성공, 실패 및 시간 초과가 있습니다. 다음 예는 성공적인 플랫폼을 보여줍니다. restoreRuntimeDone로그 메시지.


{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreRuntimeDone",
  "record":{
      "status":"success"
  }
}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

이벤트를 OTel 범위로 변환

문제 해결