Log Command

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

Sends a log message to use in a debugging context, such as the Alexa Presentation Language (APL) authoring tool Live Preview Mode or other debugging tools.

For details about previewing and debugging documents in the authoring tool, see Debug a document with the log window.

Properties

The Log command has the properties shown in the following table, in addition to the common command properties. Set the type property to Log.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property	Type	Default	Description
`level`	Enumeration	`info`	The log severity level. Accepted values: `debug`, `info`, `warn`, `error`, `critical`.
`message`	String	—	The log message.
`arguments`	Array of arguments	`[]`	Optional information to include with log message for additional context.

level

The level enumerated value represents severity. The Log command supports the levels shown in the following table, listed from least to most severe.

Level	Description
`debug`	Detailed information, used for diagnosis.
`info`	Confirming expected behavior.
`warn`	Something unexpected happened, but it's recoverable.
`error`	A problem occurred, and it might not be recoverable.
`critical`	A serious error occurred.

You can use the Log functions to convert between the enumerated levels to numeric severity. The level property can also accept a numeric value.

{
  "onPageChanged": {
    "type": "Log",
    "level": "${Level.INFO}",
    "message": "Page has changed!",
    "arguments": [
      "${event.source.value + 1}"
    ]
  }
}

message

The message property has data-binding applied at run time. You can construct the message with information from the data-binding context for the command.

arguments

The arguments property is an optional map of arbitrary key-value pairs that have data-binding applied when the command runs.

Log command example

The following example emits an info-level log in response to a page change for a Pager.

{
  "type": "APL",
  "version": "2024.3",
  "mainTemplate": {
    "items": [
      {
        "type": "Pager",
        "onPageChanged": [
          {
            "type": "Log",
            "level": "info",
            "message": "Page has changed!",
            "arguments": [
              "New page index is ${event.source.page}"
            ]
          }
        ]
      }
    ]
  }
}

For examples of viewing the log messages in the authoring tool, see Debug a document with the log window.

Disable logging in production code

Disable logging in production code to avoid any potential impact on performance. One approach is to wrap the Log command within a user-defined command.

The following example uses a bound variable called enableLogging as a flag to turn logging on and off. When the enabledLoggin variable is true, the Log command sends log messages each time the Pager changes pages.

{
  "type": "APL",
  "version": "2024.3",
  "commands": {
    "MyLog": {
      "parameters": [
        "level",
        "message",
        "arguments"
      ],
      "command": {
        "when": "${enableLogging && Log.levelValue(level) >= logVerbosity}",
        "type": "Log",
        "level": "${level}",
        "message": "${message}",
        "arguments": "${arguments}"
      }
    }
  },
  "mainTemplate": {
    "bind": [
      {
        "name": "enableLogging",
        "type": "boolean",
        "value": false
      },
      {
        "name": "logVerbosity",
        "type": "number",
        "value": "${Level.INFO}"
      }
    ],
    "items": [
      {
        "type": "Pager",
        "onPageChanged": {
          "type": "MyLog",
          "level": "info",
          "message": "Page has changed!",
          "arguments": [
            "${event.source.value + 1}"
          ]
        }
      }
    ]
  }
}

Was this page helpful?

Provide feedback

Last updated: Feb 27, 2024