API Gateway Log Storage: Pipelines, Retention, Security, and Cost

An API gateway should produce structured events and deliver them through a bounded pipeline; it should not be the long-term system of record. Store searchable operational logs in a log platform, move older data to cheaper archive storage when justified, and keep security audit records under stricter access and integrity controls.

That separation protects request processing from a slow log destination, gives each data class an explicit retention policy, and makes cost visible. It also prevents a common mistake: collecting every header and body first and deciding whether the data was safe only after it reached several systems.

Key Takeaways

• Separate log generation, transport, indexing, archive, and deletion responsibilities.
• Prefer an allowlisted schema; do not log credentials, cookies, or bodies by default.
• Give the delivery buffer a hard bound and decide what happens when the destination is unavailable.
• Treat operational access logs and security audit logs as different products with different controls.
• Set retention by purpose, investigation window, legal requirements, and cost—not by a universal number of days.
• Monitor the logging pipeline itself, including queue depth, discarded entries, delivery errors, and ingestion lag.

The Gateway Is a Producer, Not the Archive

The gateway is well placed to record the route, authenticated identity context, upstream result, and timing for each request. It is poorly placed to retain months of data: local disks are finite, gateway instances are replaced, and a storage outage must not consume all memory or block API traffic.

A production pipeline normally separates five stages:

flowchart LR
    A[API gateway\nstructured event] --> B[Bounded batch or buffer]
    B --> C[Collector or broker]
    C --> D[Hot searchable store]
    D --> E[Lower-cost archive]
    E --> F[Expiration or deletion]
    C --> G[Security analytics]

The bounded buffer absorbs short interruptions. A collector or broker normalizes delivery and decouples gateway availability from the storage backend. The hot store supports recent troubleshooting and dashboards. Archive storage is optional and should contain only data that has a defined future use. Expiration is part of the design, not an afterthought.

This article focuses on storage and delivery. For choosing logs, metrics, and traces together, see API gateway logging and monitoring best practices.

Choose the Delivery Pattern Deliberately

Apache APISIX provides logger plugins for several delivery models, including http-logger, kafka-logger, elasticsearch-logger, file-logger, and syslog. The existence of a connector does not determine the right architecture.

For most distributed deployments, a local collector or durable broker creates a cleaner failure boundary than sending every gateway instance directly to a search cluster. Direct delivery may still be reasonable when scale is modest and the team has tested failure behavior.

Design a Minimum Useful Schema

Start from the questions responders and security teams actually need to answer. A useful access event often contains:

Do not record Authorization, API keys, session cookies, secrets in query strings, or request and response bodies by default. The OWASP Logging Cheat Sheet recommends sanitizing event data and protecting logs during transport and storage. Even fields that appear harmless can become personal or confidential when combined, so document purpose and access for the whole event.

OpenTelemetry's logs data model can help normalize timestamps, severity, resource attributes, trace correlation, and the event body when logs from gateways and services share one pipeline. Adopting the model does not remove the need for redaction or retention rules.

Configure a Bounded APISIX HTTP Log Pipeline

The following APISIX 3.18 configuration excerpt defines a global allowlisted log format and a maximum pending-entry backlog for http-logger. Plugin metadata is global: it affects every Route and Service that uses this plugin, so review existing consumers before changing it.

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger" \
  -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "log_format": {
      "timestamp": "$time_iso8601",
      "request_id": "$apisix_request_id",
      "route_id": "$route_id",
      "service_id": "$service_id",
      "method": "$request_method",
      "status": "$status",
      "request_time": "$request_time",
      "upstream_response_time": "$upstream_response_time",
      "bytes_sent": "$bytes_sent"
    },
    "max_pending_entries": 8192
  }'

Next, enable delivery to an internal HTTPS collector. Certificate verification is explicit because the current http-logger default is disabled. The example intentionally omits an authentication value; use your platform's secret-management mechanism if the collector requires one rather than embedding a real secret in a Route.

curl "http://127.0.0.1:9180/apisix/admin/routes/orders-read" \
  -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "uri": "/orders/*",
    "methods": ["GET"],
    "plugins": {
      "request-id": {},
      "http-logger": {
        "uri": "https://logs.internal.example/v1/events",
        "ssl_verify": true,
        "include_req_body": false,
        "include_resp_body": false
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "orders.internal:8080": 1
      }
    }
  }'

APISIX 3.15 and later exposes $apisix_request_id as the gateway's current request ID. With request-id enabled, this is the value the plugin generated or accepted and returned in the configured response header. Because the plugin can accept a non-empty client-provided ID, do not treat the value as security evidence by itself: validate its format, keep authenticated identity in separate fields, and generate a server-controlled correlation identifier if your trust model requires one.

According to the current APISIX documentation, http-logger batches records and its metadata defaults max_pending_entries to 8,192. When the backlog exceeds the configured bound, new entries are discarded so an unreachable logger cannot grow worker memory without limit. That is a deliberate availability trade-off, not durable delivery.

If losing an access event is unacceptable, put a locally reachable durable transport in front of the central store and verify its disk and backpressure behavior. A gateway logger plugin alone should not be described as an immutable audit system.

Separate Operational Logs from Audit Records

Operational access logs answer questions such as “which route is slow?” or “which upstream returned 503?” Security audit records answer questions such as “who changed this policy?” and “who accessed protected data?” They can share some infrastructure, but they differ in provenance and controls.

An audit design may require:

• authenticated actor and administrative action details;
• append-only or tamper-evident storage;
• separation of duties for readers and administrators;
• documented evidence preservation and deletion procedures;
• alerts for access, export, or policy changes to the audit store.

Gateway request logs cannot prove an administrative event they never observed. Combine data-plane access events with control-plane configuration and identity-provider audit events where the investigation requires both.

Set Retention and Cost by Data Class

There is no safe universal retention period. Choose it by working backward from incident response, customer commitments, regulation, litigation holds, and deletion obligations.

A simple tiering model is:

• Hot: recent, indexed data for interactive search and alert investigation.
• Warm: older data with slower or less expensive query capacity.
• Archive: compressed objects kept for a defined recovery or evidence need.
• Expired: cryptographically or physically deleted according to policy, including derived copies where required.

Estimate daily volume before selecting a store:

daily ingest bytes = requests per day × average encoded event size

Use that ingestion baseline to model each stage separately. A broker estimate applies its retention window, compression ratio, and replication factor. A hot-search estimate applies indexed size, shard replicas, retention, and index overhead. Archive and backup estimates apply their own compression, duplication, and retention rules. Add network transfer and query compute once at the stage that incurs them. This prevents the same replica cost from being counted twice.

Sampling can reduce routine success-event cost, but do not sample error, security, billing, or compliance events unless the owning requirement explicitly allows it. Reducing event size through a narrow schema is often safer than collecting sensitive fields and relying on sampling.

Test the Failure Path, Not Only the Happy Path

Verify the pipeline with controlled experiments:

1. Send known requests and confirm the event schema, timestamps, and correlations.
2. Put test credentials and personal-looking values in disallowed headers and bodies; confirm they never arrive.
3. Make the collector slow, unreachable, and certificate-invalid; measure API latency and gateway memory.
4. Fill the configured backlog and confirm the expected discard behavior and alert.
5. Restore the collector and measure recovery time and ingestion lag.
6. Test retention expiration, archive retrieval, access approval, and audit trails.

APISIX's prometheus plugin exposes apisix_batch_process_entries, a gauge for entries remaining in a logger batch. Pair it with destination-side delivery errors, broker lag, index rejection, storage saturation, and the age of the newest searchable event; add an independent discard signal where your delivery design requires one.

API Gateway Log Storage Checklist

• Is each event tied to a documented operational, security, or compliance purpose?
• Are fields allowlisted and sensitive values excluded before transport?
• Is transport encrypted and is the destination identity verified?
• Is buffering bounded, with an explicit loss or backpressure policy?
• Can the pipeline survive collector, broker, index, and network failures?
• Are operational and audit data access controls appropriately separated?
• Does every storage tier have an owner, cost estimate, retention rule, and deletion test?
• Are logging-pipeline health and ingestion lag visible without depending on the same broken pipeline?

FAQ

Should an API gateway write directly to Elasticsearch?

It can, but direct delivery couples gateway instances to the search platform's availability, credentials, and schema. A collector or broker is usually preferable when volume, multiple consumers, or failure isolation matter.

How long should API gateway logs be retained?

There is no one-size-fits-all duration. Retain each data class only as long as its incident, business, contractual, legal, or regulatory purpose requires, and test deletion when that period ends.

Are API access logs the same as audit logs?

No. Access logs describe request processing. Audit logs are evidence about security-relevant actions and often need stronger provenance, integrity, access, and retention controls.

Next Steps

Use API gateway logging and monitoring best practices to connect the storage pipeline with metrics and traces. For centrally managed Apache APISIX deployments that need enterprise operations and governance, explore API7 Enterprise.