AWS API Gateway

Collect logs and metrics for AWS API Gateway with Elastic Agent.


Version	2.12.0 (View all)
Compatible Kibana version(s)	8.12.0 or higher
Supported Serverless project types What's this?	Security Observability
Subscription level What's this?	Basic

The AWS API Gateway integration allows you to monitor API Gateway — a centralized API management service.

Use the AWS API Gateway integration to collect metrics and logs related to your HTTP, REST or WebSockets APIs. Then visualize that data in Kibana, create alerts to notify you if something goes wrong, and reference metrics when troubleshooting an issue.

For example, you could use this integration to examine metrics related to error rates, response codes, and latency. You can pinpoint problematic areas, identify error-prone API endpoints, and troubleshoot performance issues.

IMPORTANT: Extra AWS charges on AWS API requests will be generated by this integration. Please refer to the AWS integration for more details.

Data streams

The API Gateway integration collects two types of data: metrics and logs.

Logs help you keep a record of events happening in Amazon API Gateway. Logs collected by the Amazon API Gateway integration include the HTTP method, status code, request details and more.

AWS API Gateway allows you to set up Custom Access Logging to gain deeper insights into the requests and responses through your API by making use of context variables (HTTP, WebSockets), input, stage and util variables (REST).

The Elastic integration for AWS API Gateway supports the following Log Format by API type:

HTTP:
{"requestId": "$context.requestId","ip": "$context.identity.sourceIp","requestTime": "$context.requestTime","httpMethod": "$context.httpMethod","routeKey": "$context.routeKey","status": "$context.status","protocol": "$context.protocol","responseLength": "$context.responseLength",apiId": "$context.apiId", "domainName": "$context.domainName", "stage": "$context.stage"}

REST:
{"requestId": "$context.requestId","ip": "$context.identity.sourceIp","caller": "$context.identity.caller","user": "$context.identity.user""requestTime": "$context.requestTime","httpMethod": "$context.httpMethod","resourcePath": "$context.resourcePath","status": "$context.status","protocol": "$context.protocol","responseLength": "$context.responseLength",apiId": "$context.apiId", "domainName": "$context.domainName", "stage": "$context.stage"}

WebSockets:
{"requestId": "$context.requestId","ip": "$context.identity.sourceIp","caller": "$context.identity.caller","user": "$context.identity.user","requestTime": "$context.requestTime","eventType": "$context.eventType","routeKey": "$context.routeKey","status": "$context.status","connectionId": "$context.connectionId", apiId": "$context.apiId", "domainName": "$context.domainName", "stage": "$context.stage"}

Beyond the standard Log Formats we provide, you can use a wide range of fields for each API type when enabling Custom Access Logging.

To utilize these fields in the integration, create custom pipelines. These pipelines will process field names or values. You'll also need to create a custom mapping to store your data efficiently. For more information on how to do this, check out our official documentation.

See more details in the Logs reference.

Metrics give you insight into the state of API Gateway. Metrics collected by the AWS API Gateway integration include the number of client and server errors, request and error counts and cache counts.

See more details in the Metrics reference.

Requirements

You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it. You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your hardware.

Before using any AWS integration you will need:

AWS Credentials to connect with your AWS account.
AWS Permissions to make sure the user you're using to connect has permission to share the relevant data.

For more details about these requirements, please take a look at the AWS integration documentation.

Setup

Use this integration if you only need to collect data from the AWS API Gateway service.

If you want to collect data from two or more AWS services, consider using the AWS integration. When you configure the AWS integration, you can collect data from as many AWS services as you'd like.

For step-by-step instructions on how to set up an integration, see the Getting started guide.

Metrics reference

An example event for apigateway looks as following:

{
    "agent": {
        "name": "docker-fleet-agent",
        "id": "fe8366bc-f3f8-4901-acce-b2c6788cf21f",
        "type": "metricbeat",
        "ephemeral_id": "dfa418e2-1fe7-4039-9e44-bec39fa60341",
        "version": "8.6.2"
    },
    "@timestamp": "2023-05-08T16:30:00.000Z",
    "ecs": {
        "version": "8.0.0"
    },
    "data_stream": {
        "namespace": "default",
        "type": "metrics",
        "dataset": "aws.apigateway_metrics"
    },
    "service": {
        "type": "aws"
    },
    "host": {
        "hostname": "docker-fleet-agent",
        "os": {
            "kernel": "5.15.90.1-microsoft-standard-WSL2",
            "codename": "focal",
            "name": "Ubuntu",
            "family": "debian",
            "type": "linux",
            "version": "20.04.5 LTS (Focal Fossa)",
            "platform": "ubuntu"
        },
        "containerized": false,
        "ip": [
            "172.18.0.7"
        ],
        "name": "docker-fleet-agent",
        "id": "f91b175388d423fca58155815dfc2279",
        "mac": [
            "02-42-AC-12-00-07"
        ],
        "architecture": "x86_64"
    },
    "elastic_agent": {
        "id": "fe8336bc-f3f1-4901-ac0a-b266788cf21f",
        "version": "8.6.2",
        "snapshot": false
    },
    "metricset": {
        "period": 300000,
        "name": "cloudwatch"
    },
    "event": {
        "duration": 10830411419,
        "agent_id_status": "verified",
        "ingested": "2023-05-08T16:39:47Z",
        "module": "aws",
        "dataset": "aws.apigateway_metrics"
    },
    "aws": {
        "apigateway": {
            "metrics": {
                "4xx": {
                    "sum": 0
                },
                "5xx": {
                    "sum": 0
                },
                "DataProcessed": {
                    "avg": 48460
                },
                "Count": {
                    "sum": 2
                },
                "IntegrationLatency": {
                    "avg": 85.5
                },
                "Latency": {
                    "avg": 104
                }
            }
        },
        "cloudwatch": {
            "namespace": "AWS/ApiGateway"
        },
        "dimensions": {
            "ApiId": "6am7mj7jqx"
        }
    }
}

Exported fields

Field	Description	Type	Unit	Metric Type
@timestamp	Event timestamp.	date
agent.id	Unique identifier of this agent (if one exists). Example: For Beats this would be beat.id.	keyword
aws.apigateway.metrics.4XXError.sum	The number of client-side errors captured in a given period.	long		gauge
aws.apigateway.metrics.4xx.sum	The number of client-side errors captured in a given period.	long		gauge
aws.apigateway.metrics.5XXError.sum	The number of server-side errors captured in a given period.	long		gauge
aws.apigateway.metrics.5xx.sum	The number of server-side errors captured in a given period.	long		gauge
aws.apigateway.metrics.CacheHitCount.sum	The number of requests served from the API cache in a given period.	long		gauge
aws.apigateway.metrics.CacheMissCount.sum	The number of requests served from the backend in a given period, when API caching is enabled.	long		gauge
aws.apigateway.metrics.ClientError.sum	The number of requests that have a 4XX response returned by API Gateway before the integration is invoked.	long		gauge
aws.apigateway.metrics.ConnectCount.sum	The number of messages sent to the connect route integration.	long		gauge
aws.apigateway.metrics.Count.sum	The total number of API requests in a given period.	long		gauge
aws.apigateway.metrics.DataProcessed.avg	The amount of data processed in bytes.	long	byte	gauge
aws.apigateway.metrics.ExecutionError.sum	Errors that occurred when calling the integration.	long		gauge
aws.apigateway.metrics.IntegrationError.sum	The number of requests that return a 4XX/5XX response from the integration.	long		gauge
aws.apigateway.metrics.IntegrationLatency.avg	The time between when API Gateway relays a request to the backend and when it receives a response from the backend.	long	ms	gauge
aws.apigateway.metrics.Latency.avg	The time between when API Gateway receives a request from a client and when it returns a response to the client.	long	ms	gauge
aws.apigateway.metrics.MessageCount.sum	The number of messages sent to the WebSocket API, either from or to the client.	long		gauge
aws.cloudwatch.namespace	The namespace specified when query cloudwatch api.	keyword
aws.dimensions.ApiId	Each API created in API Gateway is assigned a unique ApiId, which is used to distinguish and reference that specific API within the system.	keyword
aws.dimensions.ApiName	It represents a human-readable name that helps identify and differentiate the API within the API Gateway service.	keyword
aws.dimensions.Method	It represents the HTTP method which defines the action that can be performed on a resource, such as retrieving, creating, updating, or deleting data.	keyword
aws.dimensions.Resource	It represents an endpoint within the API that corresponds to a specific functionality, typically associated with a URL path segment.	keyword
aws.dimensions.Route	Routes define the path and HTTP methods that clients can use to access different functionalities of the API.	keyword
aws.dimensions.Stage	It represents a specific version of the API that is accessible to clients. A stage allows you to manage different environments or versions of your API, such as development, testing, and production.	keyword
aws.tags	Tag key-value pairs from AWS resources.	flattened
cloud	Fields related to the cloud or infrastructure the events are coming from.	group
cloud.account.id	The cloud account or organization id used to identify different entities in a multi-tenant environment. Examples: AWS account id, Google Cloud ORG Id, or other unique identifier.	keyword
cloud.account.name	The cloud account name or alias used to identify different entities in a multi-tenant environment. Examples: AWS account name, Google Cloud ORG display name.	keyword
cloud.availability_zone	Availability zone in which this host, resource, or service is located.	keyword
cloud.image.id	Image ID for the cloud instance.	keyword
cloud.instance.id	Instance ID of the host machine.	keyword
cloud.instance.name	Instance name of the host machine.	keyword
cloud.machine.type	Machine type of the host machine.	keyword
cloud.project.id	The cloud project identifier. Examples: Google Cloud Project id, Azure Project id.	keyword
cloud.provider	Name of the cloud provider. Example values are aws, azure, gcp, or digitalocean.	keyword
cloud.region	Region in which this host, resource, or service is located.	keyword
container.id	Unique container id.	keyword
container.image.name	Name of the image the container was built on.	keyword
container.labels	Image labels.	object
container.name	Container name.	keyword
data_stream.dataset	Data stream dataset.	constant_keyword
data_stream.namespace	Data stream namespace.	constant_keyword
data_stream.type	Data stream type.	constant_keyword
ecs.version	ECS version this event conforms to. `ecs.version` is a required field and must exist in all events. When querying across multiple indices -- which may conform to slightly different ECS versions -- this field lets integrations adjust to the schema version of the events.	keyword
error	These fields can represent errors of any kind. Use them for errors that happen while fetching events or in cases where the event itself contains an error.	group
error.message	Error message.	match_only_text
event.dataset	Name of the dataset. If an event source publishes more than one type of log or events (e.g. access log, error log), the dataset is used to specify which one the event comes from. It's recommended but not required to start the dataset name with the module name, followed by a dot, then the dataset name.	constant_keyword
event.module	Event module	constant_keyword
host.architecture	Operating system architecture.	keyword
host.containerized	If the host is a container.	boolean
host.domain	Name of the domain of which the host is a member. For example, on Windows this could be the host's Active Directory domain or NetBIOS domain name. For Linux this could be the domain of the host's LDAP provider.	keyword
host.hostname	Hostname of the host. It normally contains what the `hostname` command returns on the host machine.	keyword
host.id	Unique host id. As hostname is not always unique, use values that are meaningful in your environment. Example: The current usage of `beat.name`.	keyword
host.ip	Host ip addresses.	ip
host.mac	Host MAC addresses. The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen.	keyword
host.name	Name of the host. It can contain what hostname returns on Unix systems, the fully qualified domain name (FQDN), or a name specified by the user. The recommended value is the lowercase FQDN of the host.	keyword
host.os.build	OS build information.	keyword
host.os.codename	OS codename, if any.	keyword
host.os.family	OS family (such as redhat, debian, freebsd, windows).	keyword
host.os.kernel	Operating system kernel version as a raw string.	keyword
host.os.name	Operating system name, without the version.	keyword
host.os.name.text	Multi-field of `host.os.name`.	match_only_text
host.os.platform	Operating system platform (such centos, ubuntu, windows).	keyword
host.os.version	Operating system version as a raw string.	keyword
host.type	Type of host. For Cloud providers this can be the machine type like `t2.medium`. If vm, this could be the container, for example, or other information meaningful in your environment.	keyword
service.type	The type of the service data is collected from. The type can be used to group and correlate logs and metrics from one service type. Example: If logs or metrics are collected from Elasticsearch, `service.type` would be `elasticsearch`.	keyword

Logs reference