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. The maximum payload that can be logged is 2 MB. If you anticipate larger payloads, add an Activity Log policy that prevents the payload from logged for either success or error responses.

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.
For more information about how to configure your logging preferences, see activity-log policy and Including components in your assembly. For information about how to view event records that are generated for your APIs, see Viewing and exporting analytics and API event data.
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. When creating visualizations, you can use these fields to configure aggregations that define the type and level of information to be retrieved and displayed. [V5.0.8 or later]Beginning with version 5.0.8.3, you can customize which of these fields are exported to ensure that you are only storing information that you need for your visualizations. For more information, see Configuring visualizations. [V5.0.5 or later]If you have configured your logging preferences to include header and payload details, your header and payload fields will additionally be available for selection while configuring aggregations, enabling you to create visualizations based on header and payload data if required.

Table 1. API event record fields
Field name Type Description
@timestamp Date A time stamp that records when the record was written by the Logstash data collection engine that feeds data into Elasticsearch.
@version String The most recent version of the record that was written by the Logstash data collection engine that feeds data into Elasticsearch.
api_id String The API identifier.
api_name String The name of the API.
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.
[V5.0.7 or later]app_type [V5.0.7 or later]String [V5.0.7 or later]The application type, with a value of Production or Development.
[V5.0.7 or later]billing.amount [V5.0.7 or later]String [V5.0.7 or later]The amount that a customer is billed for a subscription to the Product.
[V5.0.7 or later]billing.currency [V5.0.7 or later]String [V5.0.7 or later]The monetary currency that is used to determine the subscription fee.
[V5.0.7 or later]billing.model [V5.0.7 or later]String [V5.0.7 or later]The type of billing plan that a customer is billed for a subscription to the Product.
[V5.0.7 or later]billing.provider [V5.0.7 or later]String [V5.0.7 or later]The credit card processing partner that is billing for a subscription to the Product.
[V5.0.7 or later]billing.trial_period_days [V5.0.7 or later]Integer [V5.0.7 or later]The number of days that a customer can use a billing plan without being charged.
bytes_received Number The number of bytes received on the inbound request.
bytes_sent Number The number of bytes sent on the outbound request.
catalog_id String The Catalog identifier.
catalog_name String The Catalog name.
[V5.0.8 or later]client_id [V5.0.8 or later]String [V5.0.8 or later]The unique ID of the client that is attached to the API request.
client_ip String The original client IP address, as obtained from the X-Forwarded-For header.
datetime Date A time stamp that records when the API was executed. The time stamp is always shown in coordinated universal time UTC.
debug String Debug information for the API call if APIm-Debug is set to true.
developer_org_id String The identifier for the developer organization that owns the application.
developer_org_name String The name of the developer organization that owns the application.
developer_org_title String The display title of the developer organization that owns the application.
[V5.0.8 or later]endpoint_url [V5.0.8 or later]String [V5.0.8 or later]When the request failed, identifies the proxy or invoke target URL on which the request failed. It is not included with a successful request.
gateway_ip String The IP address of the gateway.
headers.field_name String A component of the header section of a message.
host String The host name or IP address.
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.
plan_version String The version number of the Plan.
product_id String The Product identifier.
product_name String The Product name.
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.
rateLimit.count Number The number of API calls made in the defined rate limit time window.
rateLimit.limit Number The maximum number of requests an application is allowed to make to the API during a specified time window.
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.
request_method String The method of the inbound request.
request_protocol String The protocol of the inbound request.
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.
space_id String The Space identifier.
space_name String The Space name.
status_code String The status code set on the outbound response.
tags String Tags related to the API event creation.
time_to_serve_request Number The round-trip time (in milliseconds) from when the Gateway receives the API request until it returns a response to the caller, including the time spent waiting for a response to an API call to the external endpoint. The amount of time can be affected by other factors, such as custom Gateway scripts; it is not just the amount of time required by the external endpoint for processing the request. The value of this field is calculated by the gateway and passed to Analytics.
transaction_id String The identifier for the API transaction.
uri_path String The URI path on the inbound request.

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

[V5.0.7 or later]
Restriction: The billing object fields are only supported in Version 5.0.7.2, and later. 
{
  "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",
  "billing": {
     "trial_period_days": "0",
     "amount": "0",
     "currency": "USD",
     "model": "free",
     "provider": "none"  
  },
  "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)

[V5.0.7 or later]
Restriction: The billing object fields are only supported in Version 5.0.7.2, and later. 
{
  "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"
    },
    {
      "APIm-Debug": "true"
    },
    {
      "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": "APIm-Debug-Trans-Id, 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",
  "billing": {
    "trial_period_days": "0",
    "amount": "0",
    "currency": "USD",
    "model": "free",
    "provider": "none"  
  },
  "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)

[V5.0.7 or later]
Restriction: The billing object fields are only supported in Version 5.0.7.2, and later. 
{
  "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"
    },
    {
      "APIm-Debug": "true"
    },
    {
      "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": "APIm-Debug-Trans-Id, 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",
  "billing": {
    "trial_period_days": "0",
    "amount": "0",
    "currency": "USD",
    "model": "free",
    "provider": "none"  
  },
  "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
    ]
  }
}