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.
- 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
orpayload
.
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.
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:
|
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
]
}
}