Log

Overview

The Log Traffic Policy action enables you to leverage ngrok's eventing system to introduce observability into your traffic policy documents.

Configuration Reference

This is the Traffic Policy configuration reference for this action.

Action Type

log

Configuration Fields

Parameter	Type	Description
metadata	map[string]any	Required. A key-value map of metadata that you would like to include in your events for this action. Supports CEL Interpolation.

Supported Phases

• on_http_request
• on_http_response
• on_tcp_connect

Behavior

Event logs

When this action is executed, the specified metadata will be collected on the tcp_connection_closed.v0 event under the traffic_policy.logs key.

CEL Interpolation

You can access Traffic Policy variables and embed CEL expressions in this actions configuration values using CEL Interpolation in the form of ${expression}. Check out the examples below to see how CEL Interpolation works.

For a complete list of variables and how to write expressions, see Expressions and Variables documentation.

Examples

Logging with CEL Interpolation

The following Traffic Policy configuration will log a message with the endpoint identifier for every request.

Example Traffic Policy Document

YAML

---
on_http_request:
  - actions:
      - type: "log"
        config:
          metadata:
            message: "Log action executed."
            endpoint_id: "${endpoint.id}"

JSON

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "log",
          "config": {
            "metadata": {
              "message": "Log action executed.",
              "endpoint_id": "${endpoint.id}"
            }
          }
        }
      ]
    }
  ]
}

Example Request

$ curl https://example.ngrok.app

Once the request has completed, and you have properly configured an event destination, you should see an event appear with the following payload:

{
  "event_id": "ev_25X3yFS6TDkig1KDJWIc4nnJO0c",
  "event_type": "http_request_complete.v0",
  "event_timestamp": "2024-06-23T23:44:16Z",
  "account_id": "ac_2OtNvAlhso10Gx6a7eupzX3F98q",
  "object": {
    "traffic_policy": {
      "logs": [
        {
          "metadata": {
            "message": "Log action executed.",
            "endpoint_id": "ep_2bhsN2VP8W4pTkaMSrhyj0SRf8J"
          }
        }
      ]
    }
  }
}

Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

Name	Type	Description
actions.ngrok.log.metadata	map[string]string	The key-value map of metadata that was logged.