This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The MessageLogging policy lets you log custom messages toCloud Logging or syslog. You can use the information in the logs for various tasks, such as tracking down problems in the API runtime environment.

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

There are two ways to use the MessageLogging policy:

• The<CloudLogging> element logs messages to Cloud Logging. To use this method, you need to enable the Cloud Logging APIs for your Google Cloud project. For more information about enabling APIs for a Google Cloud project, seeEnabling and Disabling Services.
• The<Syslog> element logs messages to syslog, a standard protocol for sending system log or event messages to a specific server. To use this method, you must have a syslog server available. If you don't, you can use public log management services, such a Splunk, Sumo Logic, and Loggly. SeeConfiguring third-party log management services.

Note: Youcannot use both the<CloudLogging> element and the<Syslog> element in the same policy.

<MessageLogging> element

Defines a<MessageLogging> policy.

The<MessageLogging> element uses the following syntax:

<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?><MessageLoggingcontinueOnError="false"enabled="true"name="Message-Logging-1"><DisplayName>MessageLogging-1</DisplayName><Syslog><!--Note:Youcannotuseboththe<Syslog>elementandthe<CloudLogging>elementinthesamepolicy.--><Message>Somemessageforsyslog</Message><Host>localhost</Host><Port>514</Port></Syslog><CloudLogging><!--Note:Youcannotuseboththe<CloudLogging>andthe<Syslog>elementinthesamepolicy.--><LogName>projects/{organization.name}/logs/{log.id}</LogName><MessagecontentType="application/json">{"{message.queryparam.key}":"{message.queryparam.value}"}</Message><Labels><Label><Key>key1</Key><Value>value1</Value></Label><Label><Key>key2</Key><Value>value2</Value></Label></Labels><ResourceType>api</ResourceType></CloudLogging><logLevel>ALERT</logLevel></MessageLogging>

This element has the following attributes that are common to all policies:

The following table provides a high-level description of the child elements of<MessageLogging>:

Samples

<MessageLogging name="LogToCloudLogging">    <CloudLogging>        <LogName>projects/{organization.name}/logs/{log.id}</LogName>        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>        <Labels>            <Label>                <Key>key1</Key>                <Value>value1</Value>            </Label>            <Label>                <Key>key2</Key>                <Value>value2</Value>            </Label>        </Labels>        <ResourceType>api</ResourceType>    </CloudLogging></MessageLogging>

{"{message.queryparam.key}": "{message.queryparam.value}"}

<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>    <FormatMessage>true</FormatMessage>    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>  </Syslog>  <logLevel>ALERT</logLevel></MessageLogging>

<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>6514</Port>    <Protocol>TCP</Protocol>    <FormatMessage>true</FormatMessage><SSLInfo>        <Enabled>true</Enabled>    </SSLInfo>  </Syslog>  <logLevel>WARN</logLevel></MessageLogging>

Child element reference

The following sections describe the child elements of <MessageLogging>.

<CloudLogging>

Use the<CloudLogging> element to log messages to Cloud Logging.

<Label>    <Key>key1</Key>    <Value>value1</Value></Label>

Authentication for Cloud Logging

To use the<CloudLogging> element, you must deploy your API proxy to use Google authentication. Apigee will use credentials corresponding to the identity of the service account you specify in the outbound requests to Cloud Logging. For more details, seeUsing Google Authentication.

The service account that you attach to your API proxy at deployment time must have a role with thelogging.logEntries.create permission. Unless you need finer grained control, we recommend using the more inclusive predefined roleroles/logging.logWriter for the service account. For more information about Identity and Access Management (IAM) roles for<CloudLogging>, see theAccess control guide.

Proxy deployment in Apigee hybrid

If you are using Apigee hybrid, the runtime service account you create for Apigee hybrid must impersonate the proxy service account to make authenticated calls on its behalf. As a result, the Apigee hybrid runtime service account must have theiam.serviceAccountTokenCreator role for the proxy service account.

<Syslog>

Use the<Syslog> element to configure messages to be logged tosyslog. When you use the<Syslog>, an API proxy forwards log messages from Apigee to a remote syslog server. To use this method, you must have a syslog server available. If you don't, public log management services, such a Splunk, Sumo Logic, and Loggly, are available. seeConfiguring third-party log management services.

<SSLInfo>    <Enabled>true</Enabled></SSLInfo>

<logLevel>

Valid values for the<logLevel> element are:INFO (default),ALERT,WARN,ERROR.

Sets a specific level of information to be included in the message log.

If you're using the FormatMessage element (setting it to true), your<logLevel> setting affects the calculated priority score (the number inside the angle brackets) in the Apigee-generated information prepended to the message.

Usage notes

When attaching aMessageLogging policy to an API proxy flow, consider placing it in the ProxyEndpoint response, in a special flow called PostClientFlow. The PostClientFlow executes after the response is sent to the requesting client, which ensures that all metrics are available for logging. For details on using PostClientFlow, seeAPI proxy configuration reference.

The PostClientFlow is special in two ways:

1. It only executed as part of the response flow.
2. It is the only flow executed after the proxy enters the error state.

Because it is executed regardless of whether the proxy succeeded or failed, you can put MessageLogging policies in the PostClientFlow and be guaranteed that they always execute.

The following Debug image shows a MessageLogging policy executing as part of the PostClientFlow, after the DefaultFaultRule executes:

In this example, the Verify API Key policy caused the fault because of an invalid key.

Shown below is the ProxyEndpoint definition that includes the PostClientFlow:

<ProxyEndpoint name="default">  ...  <PostClientFlow>    <Response>      <Step>        <Name>Message-Logging-1</Name>      </Step>    </Response>  </PostClientFlow>  ...</ProxyEndpoint>

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

Apigee logs message asynchronously: the response is returned while the logs are still being written. As a result, no latency is introduced to your API by blocking callouts. There might be occasions when a log is not written without an error being returned, but these events are rare.

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.

Default values for variables in message template

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

<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 thedefaultVariableValue attribute on theMessage element:

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

• Splunk (select the product version)
  Also see this Apigee Community post:Log messages into Splunk
• Sumo Logic
  • Also see this Apigee Community post:Setting up Logging with Sumo Logic
  • For a complete example using Sumo Logic as the logging service, see the following Apigee Community post. The solution uses a single JavaScript policy to make HTTP POST requests to Sumo Logic HTTP Source Collector:Logging to Sumo Logic using JavaScript and HTTP
• Loggly
  When using Loggly,<FormatMessage>true</FormatMessage> is required in the policy as a child of the<Syslog> element.
  Also see this Apigee Community post for more information about message logging to Loggly:Log Messages into Loggly

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, seeWhat you need to know about policy errors andHandling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

These variables are set when a runtime error occurs. For more information, seeWhat you need to know about policy errors.

{     "fault":{      "detail":{         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"      },      "faultstring":"Execution failed"   }}

<FaultRule name="MessageLogging">    <Step>        <Name>ML-LogMessages</Name>        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>    </Step>    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition></FaultRule>

• Variables exposed by Apigee:Flow variables reference