API event record fields

An API event is logged each time an API operation is invoked, and an event record is generated for each API event in the Gateway server. The API event record contains information about the API call and the content of the record depends on the logging policy that is set for the operation.

You can use the activity-log policy to configure your logging preferences for the API event details that are stored in the Analytics component. By default, invocation details are logged if an API call is successful, and invocation, header, and payload (message body) details are logged if an API call results in an error code. To override these default settings and change the level of detail that is included in the API event record, you can add the activity-log policy to your API assembly and then configure the policy's properties. For example:
  • To include details about the request body or response body in the API event record for a successful API call, you can add an activity-log policy to the associated API operation and set the content type to payload.
  • To include details about the HTTP request headers or HTTP response headers in the API event record for a successful API call, you can add an activity-log policy to the associated API operation and set the content type to either header or payload.
  • To ensure the value in the client_geoip field is accurate, the gateway must receive the X-Forwarded-For header in all API calls. Check with the administrator of your deployment environment to ensure that the X-Forwarded-For header is passed to your gateways. For example, in a Kubernetes environment where NINGX ingresses are used, configure the NGINX ingress that is used by your gateway to use the X-Forwarded-For header: NGINX Configuration "use-forwarded-headers".
For more information about how to configure your logging preferences, see activity-log policy and Including elements in your OpenAPI 2.0 API assembly, Including elements in your OpenAPI 3.0 API assembly.
Tip: A log policy field is included in the event record to identify the logging setting. To see examples of the invocation, header, and payload details that can be included in an API event record, see:

The following table lists the static set of fields that are displayed in an API event record.

Table 1. API event record fields
Field name Type Description
@timestamp Date A timestamp that records when the record was written by the Logstash data collection engine that feeds data into OpenSearch.
api_id String The API identifier.
api_name String The name of the API.
api_resource_id String Field format is: api_name:api_version:method:path. Only available on API Gateway v10.5.0.8 or higher.
api_version String The version number of the API.
app_id String The identifier for the registered application.
app_name String The name of the registered application.
Note: The data indicates N/A when a client ID is not used or is invalid on the API. The gateway needs a client id to determine which app was invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the product that contains the API. Without a client ID, the gateway is unable to determine what plan, product, or app was invoked because a single API can belong to multiple products (each of which have multiple plans and apps subscribed to those plans with client IDs).
app_type String The application type, with a value of Production or Development.
bytes_received Number The number of bytes received from the consumer in the request.
bytes_sent Number The number of bytes sent to the consumer in the response.
client_id String The unique ID of the client that is attached to the API request.
client_geoip.area_code Number The public switched telephone network (PSTN) area code of the client, as identified from its IP address.
client_geoip.city_name String The city name of the client, as identified from its IP address.
client_geoip.continent_code String The two-letter continent code of the client, as identified from its IP address.
client_geoip.country_code2 String The two-letter country code of the client, as identified from its IP address.
client_geoip.country_code3 String The three-letter country code of the client, as identified from its IP address.
client_geoip.country_name String The country name of the client, as identified from its IP address.
client_geoip.dma_code Number The Designated Market Area (DMA) code of the client, as identified from its IP address.
client_geoip.ip String The IP address of the client.
client_geoip.latitude Number The latitude of the client location, as identified from its IP address.
client_geoip.location String The longitude and latitude of the client location (separated by a comma), as identified from its IP address.
client_geoip.longitude Number The longitude of the client location, as identified from its IP address.
client_geoip.postal_code String The postal code of the client, as identified from its IP address.
client_geoip.real_region_name String The full name of the region that corresponds to the IP address of the client.
client_geoip.region_name String The abbreviated form of the region that corresponds to the IP address of the client.
client_geoip.timezone String The time zone of the client, as identified from its IP address.
custom_data Array map Custom data can be added to this field.
datetime Date A time stamp that records when the API was executed. The time stamp is always shown in coordinated universal time UTC.
developer_org_id String The identifier for the consumer organization that owns the application.
endpoint_url String When the request failed, identifies the proxy or invoke target URL on which the request failed. It is not included with a successful request.
developer_org_name String The name of the consumer organization that owns the application.
env_id String The Catalog identifier.
env_name String The name of the Catalog.
event_id String Unique ID assigned to the event by the gateway.

Generated based on a hashed version of the datetime, transaction_id, and client_id fields combined by using the SHA1 algorithm.
gateway_geoip.area_code Number The public switched telephone network (PSTN) area code of the gateway, as identified from its IP address.
gateway_geoip.city_name String The city name of the gateway, as identified from its IP address.
gateway_geoip.continent_code String The two-letter continent code of the gateway, as identified from its IP address.
gateway_geoip.country_code2 String The two-letter country code of the gateway, as identified from its IP address.
gateway_geoip.country_code3 String The three-letter country code of the gateway, as identified from its IP address.
gateway_geoip.country_name String The country name of the gateway, as identified from its IP address.
gateway_geoip.dma_code Number The Designated Market Area (DMA) code of the gateway, as identified from its IP address.
gateway_geoip.ip String The IP address of the gateway.
gateway_geoip.latitude Number The latitude of the gateway location, as identified from its IP address.
gateway_geoip.location String The longitude and latitude of the gateway location (separated by a comma), as identified from its IP address.
gateway_geoip.longitude Number The longitude of the gateway location, as identified from its IP address.
gateway_geoip.postal_code String The postal code of the gateway, as identified from its IP address.
gateway_geoip.real_region_name String The full name of the region that corresponds to the IP address of the gateway.
gateway_geoip.region_name String The abbreviated form of the region that corresponds to the IP address of the gateway.
gateway_geoip.timezone String The time zone of the gateway, as identified from its IP address.
gateway_ip String The IP address of the gateway.
gateway_service_name String The name of the API Connect gateway service. Configured by the cloud admin user when registering the gateway service. Only available on API Gateway v10.5.0.8 or higher.
global_transaction_id String The DataPower global transaction ID. See https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varserviceglobal-transaction-id-servicevarsglobaltransactionid.
graphql_request_field_cost Number GraphQL APIs only. The maximum cost of all fields accessed in the query. The cost of each field access is configured in the schema.
graphql_request_type_cost Number GraphQL APIs only. The maximum cost of all types retrieved in the query. The cost of each type is configured in the schema.
graphql_request_max_nesting Number GraphQL APIs only. The maximum nesting depth found in the query by the assembly validate action. The schema configuration is used to determined which types are nested, so this value might be less than the nesting depth found by the assembly parse action.
graphql_response_field_cost Number GraphQL APIs only. The cost of all fields accessed in the query. The cost of each field access is configured in the schema.
graphql_response_type_cost Number GraphQL APIs only. The cost of all types that were retrieved in the query. The cost of each type is configured in the schema.
graphql_response_max_nesting Number GraphQL APIs only. The nesting depth found in the query by the assembly validate action. The schema configuration is used to determine which types are considered nested, so this value might be less than the nesting depth found by the assembly parse action.
graphql_request_top_field_counts Object GraphQL APIs only. The maximum number of times that each field can be retrieved by the given query. This number is equal to the number of times that the resolver is required to run.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_request_top_type_counts Object GraphQL APIs only. The maximum number of times that an object of each type can be retrieved by the given query.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_response_top_field_counts Object GraphQL APIs only. The number of times that each field was retrieved by the given query. This number is equal to the number of times that the resolver is required to run.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_response_top_type_counts Object GraphQL APIs only. The number of times that an object of each type was retrieved by the given query.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
headers.field_name String Internal information related to analytics ingestion. This is not related to the API call nor its response, see request_http_headers for that information.
host String The hostname or IP address of the ingestion node that received the API event.
http_user_agent String The value of the User Agent header on the inbound request.
immediate_client_ip String The client IP address that is directly in front of the gateway. In most cases this is a load balancer.
latency_info.started Number The time delay (in milliseconds) between when the request was received and when the corresponding task was started by the gateway. Starting a task comprises multiple steps to prepare for executing an API; for example, completing the TCP/TLS handshake, verifying an app's client ID and secret, and matching the request URI to a Catalog, API, and Plan. When the gateway receives a request, the "Start" duration is set to 0. The duration of each step within the Start task is then added up, and the total represents the duration of the Start task.
latency_info.task String The API transaction that was processed.
log_policy String The defined logging policy. Values include none, event, headers, and payload.
org_id String The identifier for the provider organization that owns the API and associated Products.
org_name String The name of the provider organization that owns the API and associated Products.
plan_id String The Plan identifier.
plan_name String The name of the Plan.
Note: The data indicates N/A when a client ID is not used or is invalid on the API. The gateway needs a client id to determine which app was invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the product that contains the API. Without a client ID, the gateway is unable to determine what plan, product, or app was invoked because a single API can belong to multiple products (each of which have multiple plans and apps subscribed to those plans with client IDs).
plan_version String The version number of the Plan.
product_name String The Product name.
Note: The data indicates N/A when a client ID is not used or is invalid on the API. The gateway needs a client id to determine which app was invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the product that contains the API. Without a client ID, the gateway is unable to determine what plan, product, or app was invoked because a single API can belong to multiple products (each of which have multiple plans and apps subscribed to those plans with client IDs).
product_title String The title of the Product.
product_version String The version number of the Product.
query_string String The URL query string value on the inbound request.
rate_limit.count Number The number of API calls remaining in the specified rate limit time window.
rate_limit.limit Number The maximum number of requests an application is allowed to make to the API during a specified time window.
rate_limit.period Number The time window that is used to set a rate limit for API calls.
rate_limit.reject String An indication of whether calls that exceed the specified rate limit will be rejected. If true, the API call will be rejected with a 429 status code. If false, a record is created in the Activity log.
rate_limit.shared String An indication of whether the rate limit is shared at a Plan level by all operations, or whether a rate limit is specified on individual operations.
request_body String The body of the inbound request.
request_http_headers.field_name String A component of the HTTP header section of the inbound request; for example, the acceptable encodings, the identification string for the user agent, or the proxies through which the request was sent.
Note: The following types of headers are considered sensitive and will not show in analytics data for security reasons:
  • Any secret key configured in the API security
  • Any header that contains secret
  • Any header that contains Authorization
request_method String The method of the inbound request.
request_protocol String The protocol of the inbound request.
resource String The name of the operation.
resource_id String The operation identifier.
resource_path String The operation path.
response_body String The body of the outbound response.
response_http_headers.field_name String A component of the HTTP header section of the outbound response; for example, the MIME type of the content or the data and time when the message was sent.
status_code String The status code set on the outbound response.
time_to_serve_request Number The time elapsed (in milliseconds) from when the request was received by the gateway to when it sent a response.
transaction_id String The identifier for the API transaction. See https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varservicetransaction-id-servicevarstransactionid.
uri_path String The URI path on the inbound request.

Example: Event record with invocation details (activity logging setting)

{
  "datetime": "2016-09-29T22:17:43.404Z",
  "latency_info": [
    {
      "task": "Start",
      "started": 2
    },
    {
      "task": "security-appID",
      "started": 7
    },
    {
      "task": "Plan Limit",
      "started": 11
    },
    {
      "task": "proxy",
      "started": 12
    }
  ],
  "api_version": "1.0.0",
  "product_version": "1.0.0",
  "product_name": "__INTERNAL_QS__",
  "plan_version": "1.0.0",
  "uri_path": "/macs-shack/sb/AccountService",
  "request_method": "POST",
  "log_policy": "activity",
  "request_protocol": "https",
  "query_string": [],
  "request_body": "",
  "response_body": "",
  "bytes_received": 256,
  "bytes_sent": 256,
  "time_to_serve_request": 301,
  "status_code": "200 OK",
  "request_http_headers": [],
  "response_http_headers": [],
  "org_name": "macs-shack",
  "api_name": "accountservice",
  "catalog_name": "sb",
  "resource_path": "post",
  "plan_name": "default",
  "developer_org_name": "macs-shack"
  
  "client_geoip": {
    "ip": "9.20.152.215",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  },
  "gateway_geoip": {
    "ip": "9.79.12.126",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  }
}

Example: Event record with invocation and header details (header logging setting)

{
  "datetime": "2016-09-29T22:53:46.766Z",
  "latency_info": [
    {
      "task": "Start",
      "started": 3
    },
    {
      "task": "security-appID",
      "started": 8
    },
    {
      "task": "Plan Limit",
      "started": 84
    },
    {
      "task": "activity-log",
      "started": 86
    },
    {
      "task": "proxy",
      "started": 88
    }
  ],
  "api_version": "1.0.0",
  "product_version": "1.0.0",
  "product_name": "__INTERNAL_QS__",
  "plan_version": "1.0.0",
  "uri_path": "/macs-shack/sb/AccountService",
  "request_method": "POST",
  "log_policy": "header",
  "request_protocol": "https",
  "query_string": [],
  "request_body": "",
  "response_body": "",
  "bytes_received": 256,
  "bytes_sent": 256,
  "time_to_serve_request": 317,
  "status_code": "200 OK",
  "request_http_headers": [
    {
      "Host": "apimanager.host.com"
    },
    {
      "User-Agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0"
    },
    {
      "Accept": "application/xml"
    },
    {
      "Accept-Language": "en-US,en;q=0.5"
    },
    {
      "Accept-Encoding": "gzip, deflate"
    },
    {
      "Content-Type": "text/xml"
    },
    {
      "SOAPAction": "getBalance"
    },
    {
      "Referer": "https://apimanager.host.com/apim/"
    },
    {
      "Content-Length": "256"
    },
    {
      "Origin": "https://apimanager.host.com"
    },
    {
      "Via": "1.1 AwAAABaygGU-"
    },
    {
      "X-Client-IP": "9.79.12.126"
    },
    {
      "X-Global-Transaction-ID": "1364721"
    }
  ],
  "response_http_headers": [
    {
      "Content-Type": "text/xml; charset=ISO-8859-1"
    },
    {
      "Date": "Thu, 29 Sep 2016 22:53:46 GMT"
    },
    {
      "X-Powered-By": "Servlet/3.0"
    },
    {
      "X-Vcap-Request-Id": "452d95be-0304-4f73-7429-7186ca6be843"
    },
    {
      "X-Global-Transaction-ID": "1364721"
    },
    {
      "Access-Control-Expose-Headers": "X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Global-Transaction-ID"
    },
    {
      "Access-Control-Allow-Origin": "https://apimanager.host.com"
    },
    {
      "Access-Control-Allow-Methods": "POST"
    },
    {
      "Access-Control-Allow-Credentials": "true"
    }
  ],
  "org_name": "macs-shack",
  "api_name": "accountservice",
  "catalog_name": "sb",
  "resource_path": "post",
  "plan_name": "default",
  "developer_org_name": "macs-shack",
  
  "client_geoip": {
    "ip": "9.20.152.215",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  },
  "gateway_geoip": {
    "ip": "9.79.12.126",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  }
}

Example: Event record with invocation, header, and payload details (payload logging setting)

{
  "datetime": "2016-09-29T22:26:28.667Z",
  "latency_info": [
    {
      "task": "Start",
      "started": 3
    },
    {
      "task": "security-appID",
      "started": 8
    },
    {
      "task": "Plan Limit",
      "started": 11
    },
    {
      "task": "activity-log",
      "started": 12
    },
    {
      "task": "proxy",
      "started": 269
    }
  ],
  "api_version": "1.0.0",
  "product_version": "1.0.0",
  "product_name": "__INTERNAL_QS__",
  "plan_version": "1.0.0",
  "uri_path": "/macs-shack/sb/AccountService",
  "request_method": "POST",
  "log_policy": "payload",
  "request_protocol": "https",
  "query_string": [],
  "request_body": "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\"><SOAP-ENV:Header/><SOAP-ENV:Body><ban:getBalance xmlns:ban=\"http://bankA.sample.ibm.com/\">\n  <arg0>3</arg0>\n</ban:getBalance></SOAP-ENV:Body></SOAP-ENV:Envelope>",
  "response_body": "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><ns2:getBalanceResponse xmlns:ns2=\"http://bankA.sample.ibm.com/\"><return>4</return></ns2:getBalanceResponse></soap:Body></soap:Envelope>",
  "bytes_received": 256,
  "bytes_sent": 256,
  "time_to_serve_request": 603,
  "status_code": "200 OK",
  "request_http_headers": [
    {
      "Host": "apimanager.host.com"
    },
    {
      "User-Agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0"
    },
    {
      "Accept": "application/xml"
    },
    {
      "Accept-Language": "en-US,en;q=0.5"
    },
    {
      "Accept-Encoding": "gzip, deflate"
    },
    {
      "Content-Type": "text/xml"
    },
    {
      "SOAPAction": "getBalance"
    },
    {
      "Referer": "https://apimanager.host.com/apim/"
    },
    {
      "Content-Length": "256"
    },
    {
      "Origin": "https://apimanager.host.com"
    },
    {
      "Via": "1.1 AQAAAPSLVfg-"
    },
    {
      "X-Client-IP": "9.79.12.126"
    },
    {
      "X-Global-Transaction-ID": "1204915"
    }
  ],
  "response_http_headers": [
    {
      "Content-Type": "text/xml; charset=ISO-8859-1"
    },
    {
      "Date": "Thu, 29 Sep 2016 22:26:28 GMT"
    },
    {
      "X-Powered-By": "Servlet/3.0"
    },
    {
      "X-Global-Transaction-ID": "1204915"
    },
    {
      "Access-Control-Expose-Headers": "X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Global-Transaction-ID"
    },
    {
      "Access-Control-Allow-Origin": "https://apimanager.host.com"
    },
    {
      "Access-Control-Allow-Methods": "POST"
    },
    {
      "Access-Control-Allow-Credentials": "true"
    }
  ],
  "org_name": "macs-shack",
  "api_name": "accountservice",
  "catalog_name": "sb",
  "resource_path": "post",
  "plan_name": "default",
  "developer_org_name": "macs-shack"
 
  "client_geoip": {
    "ip": "9.20.152.215",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  },
  "gateway_geoip": {
    "ip": "9.79.12.126",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  }
}