Lambda Telemetry API reference - Amazon Lambda
Subscribe
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Lambda Telemetry API reference

Use the Lambda Telemetry API endpoint to subscribe extensions to telemetry streams. You can retrieve the Telemetry API endpoint from the AWS_LAMBDA_RUNTIME_API environment variable. To send an API request, append the API version (2022-07-01/) and telemetry/. For example:

http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/

For the OpenAPI Specification (OAS) definition of the subscription responses version 2022-12-13, see the following:

API operations

Subscribe

To subscribe to a telemetry stream, a Lambda extension can send a Subscribe API request.

  • Path – /telemetry

  • Method – PUT

  • Headers

    • Content-Type: application/json

  • Request body parameters

    • schemaVersion

      • Required: Yes

      • Type: String

      • Valid values: "2022-12-13" or "2022-07-01"

    • destination – The configuration settings that define the telemetry event destination and the protocol for event delivery.

      • Required: Yes

      • Type: Object

        {
    "protocol": "HTTP",
    "URI": "http://sandbox.localdomain:8080"
}

      • protocol – The protocol that Lambda uses to send telemetry data.

        • Required: Yes

        • Type: String

        • Valid values: "HTTP"|"TCP"

      • URI – The URI to send telemetry data to.

        • Required: Yes

        • Type: String

      • For more information, see Specifying a destination protocol.

    • types – The types of telemetry that you want the extension to subscribe to.

      • Required: Yes

      • Type: Array of strings

      • Valid values: "platform"|"function"|"extension"

    • buffering – The configuration settings for event buffering.

      • Required: No

      • Type: Object

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

      • maxItems – The maximum number of events to buffer in memory.

        • Required: No

        • Type: Integer

        • Default: 1,000

        • Minimum: 1,000

        • Maximum: 10,000

      • maxBytes – The maximum volume of telemetry (in bytes) to buffer in memory.

        • Required: No

        • Type: Integer

        • Default: 262,144

        • Minimum: 262,144

        • Maximum: 1,048,576

      • timeoutMs – The maximum time (in milliseconds) to buffer a batch.

        • Required: No

        • Type: Integer

        • Default: 1,000

        • Minimum: 25

        • Maximum: 30,000

      • For more information, see Configuring memory usage and buffering.

Example Subscribe API request

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

If the Subscribe request succeeds, the extension receives an HTTP 200 success response:

HTTP/1.1 200 OK
"OK"

If the Subscribe request fails, the extension receives an error response. For example:

HTTP/1.1 400 OK
{
    "errorType": "ValidationError",
    "errorMessage": "URI port is not provided; types should not be empty"
}

Here are some additional response codes that the extension can receive:

  • 200 – Request completed successfully

  • 202 – Request accepted. Subscription request response in local testing environment

  • 400 – Bad request

  • 500 – Service error