Message Logging policy

About | Samples | Element reference | Usage notes | Flow variables | Error codes | Related topics

What

One of the best ways to track down problems in the API runtime environment is to log messages. You can attach and configure a Message Logging policy on your API to log custom messages to a local disk (on-premises only) or to syslog.

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

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

<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>
    <Protocol>TCP</Protocol>
  </Syslog>
</MessageLogging>

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 Splunk, Sumo Logic, and Loggly, are available. see Configuring third-party log management services.

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.

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 also write log messages to a file.

<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 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>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <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_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
</MessageLogging>

File rotation based on time and size

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

Stream-enabled message logging

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.


Element reference

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

File

Local file destination. (File logging is only supported in on-premises deployments of Apigee Edge.)

Message Build the message to be sent to the log file, combining text with variables to capture the information you want. See the Samples.
FileName Name of the log file where the message is logged.
FileRotationOptions
rotateFileOnStartup

Attribute. 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

To send syslog to Splunk, Sumo Logic, or Loggly, see Configuring third-party log management services.

Message Build the message to be sent to the syslog, combining text with variables to capture the information you want. See the Samples.
Host IP address of the syslog server
Port Port where the syslog is running
Protocol TCP or UDP (default). While UDP is more performant, the TCP protocol guarantees message log delivery to the syslog server.

Schemas

See our GitHub repository samples for the most recent schemas.


Usage notes

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. Edge logs message asynchronously, meaning that no latency that might be caused by blocking callouts is introduced to your API.

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 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 third-party log management services

The Message Logging policy lets you send syslog messages to third-party log management services, such as Splunk, Sumo Logic, and Loggly. If you want to send syslog to one of those services, see that service's documentation to configure the service's host, port, and protocol, then set the Syslog element on this policy accordingly.

See the following documentation for third-party log management configuration:


Flow variables

The following variable is populated on failure.

  • messagelogging.{policy_name}.failed

Related topics

 

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?)