Log Command


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.2",
  "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.2",
  "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?

Last updated: Feb 27, 2024