Was this helpful?

APIs are a message-based technology, so one of the best ways to track down problems in the runtime environment is to log messages.

Apigee Edge enables you to configure a MessageLogging policy on your API to log custom messages to a local disk or to syslog. Edge logs message asynchronously, meaning that no latency that might be caused by blocking callouts is introduced to your API.

Edge logs messages as simple text, and you can configure logging to include variables, such as the date and time when the request or response was received, the user identity on the request, the source IP address from which the request was sent, and so on. For a comprehensive list of variables exposed by Apigee Edge, see Variables reference.

Samples

The following samples illustrate different message logging configurations.

Syslog

A common usage of the MessageLogging policy type is to log to a syslog account. When configured for syslog, an API proxy will forward log messages from Apigee Edge to a remote syslog server. You may already have a sylog server available. If not, public log management services, such a loggly, are available.

For example, imagine that you need to log information about each request message that your API receives from consumer apps. The value 3f509b58 represents a key value specific to the loggly service. If you have a loggly account, substitute your loggly key. The log message that is generated will be populated with four values: the organization, API proxy, and environment name associated with the transaction, along with the value for a query parameter on the request message.

<MessageLogging name="LogToSyslog">>
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
  </Syslog>
</MessageLogging>

Host and Port elements cannot refer to variables. They must contain static values.

If you have an on-premises deployment of Apigee Edge, you can deploy to you can also write log messages to a file.

Log Destination

A number of configurations are supported for logging messages to a file on the Apigee Edge management server.

File logging is only supported in on-premises deployments of Apigee Edge.

File rotation based on file size

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageId}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
</MessageLogging>

File rotation based on time

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageId}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
</MessageLogging>

File rotation based on time and size

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageId}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
</MessageLogging>

Stream-enabled message logging

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

If HTTP streaming is enabled in an API proxy, neither request nor response messages will be buffered by processing pipeline. When you need to log parsed message content, set BufferMessage to true.

The MessageLogging policy writes logged messages in memory to a buffer. The message logger reads messages from the buffer and then writes to the destination that you configure. Each destination has its own buffer.

If the write rate to the buffer increases beyond the read rate, the buffer overflows and logging will fail. If you encounter this issue in an On-Premises deployment of Apigee Edge, locate the message-logging.properties and use this solution:

Increase the max.log.message.size.in.kb property (default value = 128 KB) in the message-logging.properties file.

Default values for variables in message template

Default values can be specified for each variable in message template separately. For example, if the variable request.header.id cannot be resolved, then its value is replaced with the value unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

A common default value can be specified for all the unresolved variables by setting the defaultVariableValue attribute on the the Message element:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Configuring the MessageLogging policy

Use the following elements to configure the MessageLogging policy type.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Field Description
Local file destination. (File logging is only supported in on-premises deployments of Apigee Edge.) FileName Name of the log file where the message is logged.
rotateFileOnStartup

Valid values: true/false

If set to true, then the log file is rotated every time the messaging engine restarts.

FileRotationType Specifies the rotation policy (size or time) of a log file.
MaxFileSizeInMB (On selecting size as rotation type) Specifies the size of a log file that triggers the server to move log messages to a separate file. After the log file reaches the specified size, the server renames the current log file.
RotationFrequency (On selecting time as rotation type) Specifies the time in minutes that triggers the server to move log messages to a separate file. After the specified interval elapses, the current log file is renamed.
MaxFilesToRetain Specifies the maximum number of files to be retained on rotation policy.
Syslog destination Host IP address of the syslog server
Port Port where the syslog is running

Policy-specific variables

The following variable is populated on failure.

  • messagelogging.{policy_name}.failed

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)