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.
    Restriction: The payload logging feature is disabled for IBM® Cloud instances that are hosted in the Frankfurt region. The requirements for storing Sensitive Personal Information (SPI) are more restrictive in that region, so the payload information cannot be saved.
  • 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.
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. For more information, see Configuring visualizations. 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.

Note: If you want to include the client_geoip and gateway_geoip fields in your Analytics data, ask your administrator to configure it as explained in Configuring output plugins for analytics offload.
Table 1. API event record fields
Field name Type Description
datetime Date A time stamp that records when the record 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.
app_type String The application type, with a value of Production or Development.
bytes_received Number The number of bytes received on the inbound request.
bytes_sent Number The number of bytes sent on the outbound 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.
client_id String 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.
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.
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.
headers.field_name String A component of the header section of a message.
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
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_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.
rate_limit.count Number The number of API calls made in the defined 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.
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 backend application to when it sent a response.
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)

{
  "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"
    },
    {
      "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",
  
  "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"
    },
    {
      "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",
 
  "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
    ]
  }
}