텔레메트리 API를 사용하여 확장의 실시간 텔레메트리 데이터에 액세스

텔레메트리 API를 사용하면 확장에서 Lambda로부터 텔레메트리 데이터를 직접 수신할 수 있습니다. 함수 초기화 및 간접 호출 중에 Lambda는 로그, 플랫폼 지표, 플랫폼 트레이스와 같은 텔레메트리를 자동으로 캡처합니다. 텔레메트리 API를 사용하면 확장에서 Lambda로부터 거의 실시간으로 이 텔레메트리 데이터에 직접 액세스할 수 있습니다.

Lambda 실행 환경 내에서 텔레메트리 스트림에 대한 Lambda 확장을 구독할 수 있습니다. 구독 후 Lambda는 모든 텔레메트리 데이터를 확장으로 자동 전송합니다. 그런 다음 유연하게 데이터를 처리 및 필터링하고 Amazon Simple Storage Service(S3) 버킷 또는 타사 관찰성 도구 제공업체와 같은 원하는 대상으로 전송할 수 있습니다.

다음 다이어그램은 확장 API와 텔레메트리 API가 실행 환경 내에서 확장을 Lambda에 연결하는 방법을 보여줍니다. 또한 런타임 API는 런타임 및 함수를 Lambda에 연결합니다.

확장은 텔레메트리 API를 사용하여 세 가지 텔레메트리 스트림을 구독할 수 있습니다.

텔레메트리 API를 사용하여 확장 생성

Lambda 확장은 실행 환경에서 독립 프로세스로 실행됩니다. 함수 간접 호출이 완료된 후에도 확장을 계속 실행할 수 있습니다. 화장은 별도의 프로세스로 실행되므로 함수 코드와 다른 언어로 작성할 수 있습니다. Golang 또는 Rust와 같은 컴파일된 언어를 사용하여 확장을 작성하는 것이 좋습니다. 이 경우 확장은 지원되는 모든 런타임과 호환되는 독립형 바이너리입니다.

다음 다이어그램은 텔레메트리 API를 사용하여 텔레메트리 데이터를 수신하고 처리하는 확장을 생성하는 4단계 프로세스를 보여줍니다.

다음은 각 단계에 대한 자세한 내용입니다.

확장 등록

텔레메트리 데이터를 구독하려면 먼저 Lambda 확장을 등록해야 합니다. 등록은 확장 초기화 단계에서 이루어집니다. 다음 예제에서는 확장을 등록하는 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 참조을 참조하세요.

텔레메트리 리스너 생성

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 리스너 또는 TCP 포트를 설정합니다. 설치하는 동안 다음 사항에 유의하세요.

메모리 사용량 및 버퍼링 구성

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

텔레메트리 API를 사용하여 텔레메트리를 수신하기 위해 구독하면 텔레메트리 데이터를 버퍼링하여 구독자에게 배치로 전달하는 옵션이 제공됩니다. 메모리 사용량을 최적화하기 위해 버퍼링 구성을 지정할 수 있습니다.

{
    "buffering": {
        "maxBytes": 256*1024,
        "maxItems": 1000,
        "timeoutMs": 100
    }
}

버퍼링을 설정할 때 다음 사항을 고려합니다.

텔레메트리 API에 구독 요청 전송

Lambda 확장은 텔레메트리 API에 구독 요청을 전송하여 텔레메트리 데이터를 수신하도록 구독할 수 있습니다. 이 구독 요청에는 확장이 구독하도록 하려는 이벤트 유형에 대한 정보가 포함되어야 합니다. 또한 이 요청에는 전송 대상 정보와 버퍼링 구성이 포함될 수 있습니다.

구독 요청을 전송하려면 먼저 확장 ID(Lambda-Extension-Identifier)가 있어야 합니다. 확장 API를 사용하여 확장을 등록할 때 API 응답에서 확장 ID를 얻습니다.

구독은 확장 초기화 단계에서 이루어집니다. 다음 예에서는 플랫폼 텔레메트리, 함수 로그, 확장 로그의 세 가지 텔레메트리 스트림을 모두 구독하는 HTTP 요청을 보여줍니다.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
   "schemaVersion": "2022-12-13",
   "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
}

다음 표에는 모든 유형의 Event 객체가 요약되어 있으며 각 이벤트 유형의 텔레메트리 APIEvent 스키마 참조에 대한 링크가 나와 있습니다.