Gateway Access Logs

Introduction

An Access Log is a single log line written at info severity to stderr for every request Tyk Gateway handles, giving you a lightweight, real-time record of individual requests. This is a different mechanism from an API Traffic Log, which also records individual requests but is written to Redis and processed asynchronously by Tyk Pump, carrying richer detail as a result. Access Logs are generated by the same logger as Tyk Gateway’s Application Log, so their severity, format, and third-party output are all controlled by the same shared settings:

verbosity: which severity levels are written (must be info or debug for Access Logs to be recorded at all)
format: the structure and timestamp style of each entry
log output: where logs are sent, for example to a third-party aggregator

See Configuring Application and Access Logs for details of these and how to configure them. Access Logs have two additional settings of their own, covered below: whether they’re generated at all (Enabling Access Logs), and which fields they include (Access Log Content).

Availability

Component	Version	Edition
Tyk Gateway	Available since v5.8.0	Community & Enterprise

Access Logs are not available on Tyk Cloud.

Enabling Access Logs

Access Logs are disabled by default. Set access_logs.enabled to true to turn them on:

Configuration File
Environment Variables

Configuration using tyk.conf:

{
    "access_logs": {
        "enabled": true
    }
}

Configuration using environment variables:

TYK_GW_ACCESSLOGS_ENABLED=true

Access Log Content

Each Access Log entry contains:

timestamp
the log severity (always info)
prefix, always set to access-log; this identifies the entry as an Access Log, since Application Log entries are written to the same output but use other prefix values.
a configurable list of key-value pairs giving details of the request (for example API ID or HTTP response status code)

For example:

time="2025-01-29T08:27:09Z" level=info api_id=b1a41c9a89984ffd7bb7d4e3c6844ded api_key=00000000 api_name=httpbin api_type=oas client_ip="::1" host="localhost:8080" latency_gateway=1 latency_total=62 method=GET org_id=678e6771247d80fd2c435bf3 original_path=/get path=/get prefix=access-log protocol=HTTP/1.1 remote_addr="[::1]:63251" status=200 trace_id=4bf92f3577b34da6a3ce929d0e0e4736 upstream_addr="http://httpbin.org/get" upstream_latency=61 user_agent=PostmanRuntime/7.43.0

The keys that will be included in the logs are configured using an access log template. If no template is configured, then all available fields will be included in each log entry. The prefix field is always included, whether or not a template is configured. The full list of available fields that can be included in an access log is here.

Field order is predictable, not arbitrary: time and level always come first, followed by every other field in alphabetical order.

Access Log Templates

You can define an access log template to reduce the size of the access log by including only a subset of the available fields. This is a simple list of field names declared in the Tyk Gateway configuration as a template array within the access_logs object. For example:

Configuration File
Environment Variables

Configuration using tyk.conf

{
    "access_logs": {
        "enabled": true,
        "template": [
            "api_key",
            "remote_addr",
            "upstream_addr"
        ]
    }
}

Configuration using environment variables:

TYK_GW_ACCESSLOGS_ENABLED=true
TYK_GW_ACCESSLOGS_TEMPLATE="api_key,remote_addr,upstream_addr"

Output:

time="2025-01-29T08:27:48Z" level=info api_key=00000000 prefix=access-log remote_addr="[::1]:63270" upstream_addr="http://httpbin.org/get"

Only the three templated fields appear, plus prefix, which is always included regardless of the template.

MCP-Specific Fields

When the log is generated for a request to an MCP Proxy, MCP-specific fields are added to the access log:

mcp_method
mcp_primitive_type
mcp_primitive_name
mcp_error_code

These fields are omitted when empty, so non-MCP logs are unaffected. Examples

MCP tools/call request (success)

When an AI client calls a tool via an MCP Proxy:

time="2025-04-07T10:15:30Z" level=info api_id=mcp-weather-api api_name=weather-mcp api_type=mcp
  latency_total=143 mcp_method=tools/call
  mcp_primitive_name=get_current_weather mcp_primitive_type=tool
  method=POST path=/mcp prefix=access-log status=200

Key fields:

api_type=mcp identifies this as an MCP Proxy request.
mcp_method=tools/call indicates the JSON-RPC method invoked.
mcp_primitive_type=tool and mcp_primitive_name=get_current_weather identify the specific tool that was called.

MCP tools/call request (error)

When the upstream MCP server returns a JSON-RPC error:

time="2025-04-07T10:16:02Z" level=info api_id=mcp-weather-api api_name=weather-mcp api_type=mcp
  latency_total=38 mcp_error_code=-32602 mcp_method=tools/call
  mcp_primitive_name=get_forecast mcp_primitive_type=tool
  method=POST path=/mcp prefix=access-log status=200

Note that JSON-RPC errors are typically returned with HTTP 200 (as per the JSON-RPC spec). The mcp_error_code field identifies the error, and response_flag will reflect the gateway classification.

Access Log Field Reference

ID of the requested API definition. Present whenever the request matched an API.

Obfuscated or hashed API key used in the request.

Name of the requested API definition. Present whenever the request matched an API.

API type classification. One of mcp, graphql, oas, or classic. Always present.

Circuit breaker state (for example, OPEN), only present on circuit breaker errors.

IP address of the client making the request.

Gateway component that generated the error, only present on error requests.

Upstream address being accessed, only present on upstream or proxy errors.

Hostname of the request.

Time spent in Tyk Gateway’s own processing, separate from the upstream round trip.

Total time taken to process the request, including upstream latency and additional gateway processing.

JSON-RPC error code when the MCP request fails (for example, -32001 for Authentication required, -32002 for Access denied). Only present when an MCP error occurs.

JSON-RPC method called on an MCP Proxy (for example, tools/call, initialize, resources/read). Only present on MCP Proxy requests.

Name of the MCP tool, resource, or prompt that was invoked. Only present on MCP Proxy requests.

MCP primitive type invoked: tool, resource, or prompt. Only present on MCP Proxy requests.

HTTP method used in the request (for example, GET or POST).

Organisation ID of the requested API definition. Present whenever the request matched an API.

The client’s request path, captured before Tyk Gateway applies any path-modifying middleware, such as stripping the API’s listen path. Equal to path unless something changes the path during processing.

URL path of the request.

Protocol used in the request (for example, HTTP/1.1).

Remote address of the client.

Detailed error description in snake_case, only present on error requests.

Error classification code, only present on error requests. See Error Classification.

HTTP response status code.

TLS certificate expiration date in RFC 3339 format, only present on TLS certificate errors.

TLS certificate subject (for example, CN=api.example.com), only present on TLS certificate errors.

The OpenTelemetry trace ID for the request (32-character hex W3C trace ID). Only present when OpenTelemetry is enabled and a trace ID is available. Use this to navigate from an access log entry to the corresponding trace in your observability backend.

Full upstream address, including scheme, host, and path.

Round-trip duration between the gateway sending the request to the upstream service and receiving the response.

HTTP status code returned by the upstream, only present when the upstream responds with a 5XX status.

User agent string provided by the client.

Error Classification

Access logs include a small set of additional fields when a request fails, so you can diagnose problems, such as TLS certificate expiry, connection refusal, or authentication errors, directly from the log without cross-referencing application or API Traffic Logs. Whether a given field appears depends on the specific error; each field’s exact conditions are noted in Access Log Field Reference above. Two fields anchor this classification: response_flag and error_source.

Error classification fields are omitted entirely, not set to an empty string or zero, when they don’t apply. This keeps successful requests and errors that don’t trigger a given field unchanged.

Response Flags

A response flag is a short, fixed code, such as UCF or AKI, that classifies the specific error condition Tyk Gateway encountered while processing the request. response_flag values are shared with Tyk Gateway’s error response customization feature, which uses the same flags to match errors you want to override. See the Flag Reference there for the full list, what each one means, and its typical HTTP status.

Error Source

error_source identifies the Gateway component that generated the error, helping you locate where in the request pipeline the failure occurred. It’s present alongside response_flag on every error entry.

error_source	Component	Typical flags
`ReverseProxy`	Upstream proxy and transport layer	`UCF`, `TLE`, `URT`, `DNS`, `CBO`, `NHU`
`Upstream`	The upstream server itself (responded with error)	`URS`
`AuthKey`	Auth Token middleware	`AMF`, `AKI`, `TKE`
`Oauth2KeyExists`	OAuth2 middleware	`AMF`, `AKI`, `EAD`
`JWTMiddleware`	JWT middleware	`AMF`, `TKI`, `TCV`, `TKE`
`BasicAuthMiddleware`	Basic Auth middleware	`AMF`, `IHD`, `BIV`
`RateLimitAndQuotaCheck`	Rate limiting and quota middleware	`RLT`, `QEX`
`APIRateLimitMiddleware`	API-level rate limiting	`RLT`
`RequestSizeLimitMiddleware`	Request size limit middleware	`BTL`, `CLM`
`ValidateJSONMiddleware`	JSON schema validation middleware	`BIV`

Examples

Upstream connection refused (500)

When the upstream server refuses the TCP connection, the access log shows:

time="2025-02-10T14:23:01Z" level=info api_id=abc123 api_name=my-api api_type=oas
  error_source=ReverseProxy error_target=api.backend.com:443
  method=GET path=/users prefix=access-log
  response_code_details=connection_refused response_flag=UCF status=500

Key fields:

response_flag=UCF identifies the error as an Upstream Connection Failure.
error_target=api.backend.com:443 shows the specific upstream that refused the connection.
upstream_status is absent because no HTTP response was received from the upstream.

TLS certificate expired (500)

When the upstream’s TLS certificate has expired:

time="2025-02-10T14:25:33Z" level=info api_id=abc123 api_name=my-api api_type=oas
  error_source=ReverseProxy error_target=api.backend.com:443
  method=GET path=/users prefix=access-log
  response_code_details=tls_certificate_expired response_flag=TLE status=500
  tls_cert_expiry=2024-01-15T00:00:00Z tls_cert_subject="CN=api.backend.com"

The tls_cert_expiry and tls_cert_subject fields help you identify exactly which certificate needs renewal and when it expired.

Circuit breaker open (503)

When a circuit breaker trips for an endpoint, the access log shows:

time="2025-02-10T14:30:00Z" level=info api_id=abc123 api_name=my-api api_type=oas
  circuit_breaker_state=OPEN error_source=ReverseProxy error_target=api.backend.com:443/health
  method=GET path=/health prefix=access-log
  response_code_details=circuit_breaker_open response_flag=CBO status=503

Rate limited (429)

When a client exceeds the configured rate limit, the access log shows:

time="2025-02-10T14:31:22Z" level=info api_id=abc123 api_name=my-api api_type=oas
  error_source=RateLimitAndQuotaCheck method=POST path=/orders prefix=access-log
  response_code_details=session_rate_limited response_flag=RLT status=429

Note that error_target is absent for gateway-level errors (authentication, rate limiting, validation) because the request did not reach the upstream.

Upstream returned 503 (5XX passthrough)

When the upstream receives the request but responds with an error status, the access log shows:

time="2025-02-10T14:32:45Z" level=info api_id=abc123 api_name=my-api api_type=oas
  error_source=Upstream error_target=api.backend.com:443
  method=GET path=/health prefix=access-log
  response_code_details=upstream_response_5xx response_flag=URS status=503
  upstream_status=503

Key distinction: error_source=Upstream and upstream_status=503 indicate that the upstream returned an error, unlike a connection failure, where no response was received.

Performance Considerations

Enabling access logs introduces some performance overhead:

Latency: Increases consistently by approximately 4%-13%, depending on CPU allocation and configuration.
Memory Usage: Memory consumption increases by approximately 6%-7%.
Allocations: The number of memory allocations increases by approximately 5%-6%.

While the overhead of enabling access logs is noticeable, the impact is relatively modest. These findings suggest the performance trade-off may be acceptable depending on the criticality of logging to your application.

Troubleshooting

Distinguishing Connection Errors from Upstream Response Errors

A common troubleshooting question is whether the upstream received the request or if the connection itself failed. The error classification fields make this distinction clear:

Scenario	`error_source`	`upstream_status`	`error_target`	Example flags
Connection failed (upstream never received request)	`ReverseProxy`	absent (0)	present	`UCF`, `UCT`, `DNS`, `TLE`
Upstream responded with error	`Upstream`	present (for example, 503)	present	`URS`
Gateway rejected request (never proxied)	middleware name	absent	absent	`RLT`, `AMF`, `BTL`

Getting Started

Deploy Tyk

Design & Create APIs

Secure APIs

Control Traffic

Routing Traffic

Transform Traffic

Observe APIs

Maintain APIs

Platform Administration

Guides

Reference

Developer Support

Introduction

Availability

Enabling Access Logs

Access Log Content

Access Log Templates

MCP-Specific Fields

Access Log Field Reference

Error Classification

Response Flags

Error Source

Examples

Performance Considerations

Troubleshooting

​Introduction

​Availability

​Enabling Access Logs

​Access Log Content

​Access Log Templates

​MCP-Specific Fields

​Access Log Field Reference

​Error Classification

​Response Flags

​Error Source

​Examples

​Performance Considerations

​Troubleshooting

Introduction

Availability

Enabling Access Logs

Access Log Content

Access Log Templates

MCP-Specific Fields

Access Log Field Reference

Error Classification

Response Flags

Error Source

Examples

Performance Considerations

Troubleshooting