# Logging - Thread Stack

# Logging - Thread Stack

This module includes OpenThread logging related definitions.

## Summary

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gac296c41b2961c2bb99f06396be2d0825(const char *aText, const void *aData, uint16_t aDataLength)` | `void` Generates a memory dump at critical log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga636552593685b0bceb727fee33f04de9(const char *aText, const void *aData, uint16_t aDataLength)` | `void` Generates a memory dump at debug log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga01a18c68b8c59fdb8ced2c2a0681ce3b(const char *aText, const void *aData, uint16_t aDataLength)` | `void` Generates a memory dump at info log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gad6aaaa24a609809b1d1e5cc9bdaf23a5(const char *aText, const void *aData, uint16_t aDataLength)` | `void` Generates a memory dump at note log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga6a2e97749dbd5447c8e232864a45724c(const char *aText, const void *aData, uint16_t aDataLength)` | `void` Generates a memory dump at warning log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gaac60eb3f1f11e8e07e669fe3035e2697(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb` Returns the current log level for a given OpenThread instance. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gae632525f546ca22ac4452e39c2cf36db(https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb aLogLevel, const char *aFormat, ...)` | `void` Emits a log message at a given log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga18adf5bb039b8af670a03451f59e6075(const char *aFormat, ...)` | `void` Emits a log message at critical log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gab775428b4f12eaf1bed5ff40cd435e10(const char *aFormat, ...)` | `void` Emits a log message at debug log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga514dd8cd606ac65043747e2783719dee(https://openthread.io/reference/struct/ot-log-hex-dump-info *aInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Generates the next hex dump line. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga8f2116f5c71f8a95cf3bd8dafacd810f(const char *aFormat, ...)` | `void` Emits a log message at info log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga5bdc0b2dab069023d680884acedd1ce6(const char *aFormat, ...)` | `void` Emits a log message at note log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gacb76ebf2facd807b98d71437524da1e8(https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb aLogLevel, const char *aPlatModuleName, const char *aFormat, ...)` | `void` Emits a log message at given log level using a platform module name. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga6d641b229b66e749165a393801a57876(https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb aLogLevel, const char *aPlatModuleName, const char *aFormat, va_list aArgs)` | `void` Emits a log message at given log level using a platform module name. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gab5f0c8f3846a13bdee6351294c218b44(const char *aFormat, ...)` | `void` Emits a log message at warning log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga119a0a463c117af8e37a6c954f5c88ad(void)` | `https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb` Returns the current global log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1gad2468bc293c95479e21b449261e3c73b(https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb aLogLevel)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the global log level. |
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga543ea6e4d0ccebbad6dddbcea361f500(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/plat-logging#group__plat-logging_1ga6ac756046db5c24c6c068139b689dbdb aLogLevel)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the log level for a given OpenThread instance. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-logging#group__api-logging_1ga6e208d49e32beb6500e3ff013cbe94e5 73` | Hex dump line string size. |

| ### Structs ||
|---|---|
| [otLogHexDumpInfo](https://openthread.io/reference/struct/ot-log-hex-dump-info) | Represents information used for generating hex dump output. |

## Functions

### otDumpCritPlat

```
void otDumpCritPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)
```
Generates a memory dump at critical log level.

If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below critical this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aText` | A string that is printed before the bytes. | | `[in] aData` | A pointer to the data buffer. | | `[in] aDataLength` | Number of bytes in `aData`. | |

### otDumpDebgPlat

```
void otDumpDebgPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)
```
Generates a memory dump at debug log level.

If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below debug this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aText` | A string that is printed before the bytes. | | `[in] aData` | A pointer to the data buffer. | | `[in] aDataLength` | Number of bytes in `aData`. | |

### otDumpInfoPlat

```
void otDumpInfoPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)
```
Generates a memory dump at info log level.

If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below info this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aText` | A string that is printed before the bytes. | | `[in] aData` | A pointer to the data buffer. | | `[in] aDataLength` | Number of bytes in `aData`. | |

### otDumpNotePlat

```
void otDumpNotePlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)
```
Generates a memory dump at note log level.

If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below note this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aText` | A string that is printed before the bytes. | | `[in] aData` | A pointer to the data buffer. | | `[in] aDataLength` | Number of bytes in `aData`. | |

### otDumpWarnPlat

```
void otDumpWarnPlat(
  const char *aText,
  const void *aData,
  uint16_t aDataLength
)
```
Generates a memory dump at warning log level.

If `OPENTHREAD_CONFIG_LOG_PLATFORM` or `OPENTHREAD_CONFIG_LOG_PKT_DUMP` is not set or the current log level is below warning this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aText` | A string that is printed before the bytes. | | `[in] aData` | A pointer to the data buffer. | | `[in] aDataLength` | Number of bytes in `aData`. | |

### otGetLogLevel

```
otLogLevel otGetLogLevel(
  otInstance *aInstance
)
```
Returns the current log level for a given OpenThread instance.

If dynamic log level feature `OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE` is enabled, this function returns the currently set dynamic log level:

- In a single-instance configuration, it returns the instance's log level.
- In a multi-instance configuration, it returns the instance-specific log level if it has been explicitly set (see `https://openthread.io/reference/group/api-logging#group__api-logging_1ga543ea6e4d0ccebbad6dddbcea361f500`). Otherwise, it returns the global log level (see `https://openthread.io/reference/group/api-logging#group__api-logging_1ga119a0a463c117af8e37a6c954f5c88ad`).

<br />

If the dynamic log level feature is not enabled, this function returns the build-time configured log level.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| **Returns** | The log level. |

### otLogCli

```
void otLogCli(
  otLogLevel aLogLevel,
  const char *aFormat,
  ...
)
```
Emits a log message at a given log level.

Is intended for use by CLI only. If `OPENTHREAD_CONFIG_LOG_CLI` is not set or the current log level is below the given log level, this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aLogLevel` | The log level. | | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLogCritPlat

```
void otLogCritPlat(
  const char *aFormat,
  ...
)
```
Emits a log message at critical log level.

Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below critical, this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLogDebgPlat

```
void otLogDebgPlat(
  const char *aFormat,
  ...
)
```
Emits a log message at debug log level.

Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below debug, this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLogGenerateNextHexDumpLine

```
otError otLogGenerateNextHexDumpLine(
  otLogHexDumpInfo *aInfo
)
```
Generates the next hex dump line.

Can call this method back-to-back to generate the hex dump output line by line. On the first call the `mIterator` field in `aInfo` MUST be set to zero.

Here is an example of the generated hex dump output:

"==========================\[{mTitle} len=070\]============================" "\| 41 D8 87 34 12 FF FF 25 \| 4C 57 DA F2 FB 2F 62 7F \| A..4...%LW.../b. \|" "\| 3B 01 F0 4D 4C 4D 4C 54 \| 4F 00 15 15 00 00 00 00 \| ;..MLMLTO....... \|" "\| 00 00 00 01 80 DB 60 82 \| 7E 33 72 3B CC B3 A1 84 \| ......\`.\~3r;.... \|" "\| 3B E6 AD B2 0B 45 E7 45 \| C5 B9 00 1A CB 2D 6D 1C \| ;....E.E.....-m. \|" "\| 10 3E 3C F5 D3 70 \| \| .\>\<..p \|" "---"

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in,out] aInfo` | A pointer to `https://openthread.io/reference/struct/ot-log-hex-dump-info` to use to generate hex dump. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully generated the next line, `mLine` field in `aInfo` is updated. | | `OT_ERROR_NOT_FOUND` | Reached the end and no more line to generate. | |

### otLogInfoPlat

```
void otLogInfoPlat(
  const char *aFormat,
  ...
)
```
Emits a log message at info log level.

Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below info, this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLogNotePlat

```
void otLogNotePlat(
  const char *aFormat,
  ...
)
```
Emits a log message at note log level.

Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below note, this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLogPlat

```
void otLogPlat(
  otLogLevel aLogLevel,
  const char *aPlatModuleName,
  const char *aFormat,
  ...
)
```
Emits a log message at given log level using a platform module name.

This is is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below `aLogLevel` , this function does not emit any log message.

The `aPlatModuleName` name is used to determine the log module name in the emitted log message, following the `P-{PlatModuleName}---` format. This means that the prefix string "P-" is added to indicate that this is a platform sub-module, followed by the next 12 characters of the `PlatModuleName` string, with padded hyphens `-` at the end to ensure that the region name is 14 characters long.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aLogLevel` | The log level. | | `[in] aPlatModuleName` | The platform sub-module name. | | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLogPlatArgs

```
void otLogPlatArgs(
  otLogLevel aLogLevel,
  const char *aPlatModuleName,
  const char *aFormat,
  va_list aArgs
)
```
Emits a log message at given log level using a platform module name.

This is is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below `aLogLevel` , this function does not emit any log message.

The `aPlatModuleName` name is used to determine the log module name in the emitted log message, following the `P-{PlatModuleName}---` format. This means that the prefix string "P-" is added to indicate that this is a platform sub-module, followed by the next 12 characters of the `PlatModuleName` string, with padded hyphens `-` at the end to ensure that the region name is 14 characters long.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aLogLevel` | The log level. | | `[in] aPlatModuleName` | The platform sub-module name. | | `[in] aFormat` | The format string. | | `[in] aArgs` | Arguments for the format specification. | |

### otLogWarnPlat

```
void otLogWarnPlat(
  const char *aFormat,
  ...
)
```
Emits a log message at warning log level.

Is intended for use by platform. If `OPENTHREAD_CONFIG_LOG_PLATFORM` is not set or the current log level is below warning, this function does not emit any log message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aFormat` | The format string. | | `[in] ...` | Arguments for the format specification. | |

### otLoggingGetLevel

```
otLogLevel otLoggingGetLevel(
  void
)
```
Returns the current global log level.

In a single-instance configuration, this function behaves the same as `https://openthread.io/reference/group/api-logging#group__api-logging_1gaac60eb3f1f11e8e07e669fe3035e2697`. In a multi-instance configuration, it returns the global log level which is used for all instances.

<br />

| Details ||
|---|---|
| **Returns** | The global log level. |

### otLoggingSetLevel

```
otError otLoggingSetLevel(
  otLogLevel aLogLevel
)
```
Sets the global log level.

<br />

> [!NOTE]
> **Note:** This function requires `OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE=1`.

In a single-instance configuration, this function behaves the same as `https://openthread.io/reference/group/api-logging#group__api-logging_1ga543ea6e4d0ccebbad6dddbcea361f500` (which is the recommended function to use).

<br />

In a multi-instance configuration, it sets the global log level which is used by all instances. The log level can be explicitly set on a specific instance using `https://openthread.io/reference/group/api-logging#group__api-logging_1ga543ea6e4d0ccebbad6dddbcea361f500`, which will then be used instead of the global value.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aLogLevel` | The log level. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully updated the log level. | | `OT_ERROR_INVALID_ARGS` | Log level value is invalid. | |

### otSetLogLevel

```
otError otSetLogLevel(
  otInstance *aInstance,
  otLogLevel aLogLevel
)
```
Sets the log level for a given OpenThread instance.

<br />

> [!NOTE]
> **Note:** This function requires `OPENTHREAD_CONFIG_LOG_LEVEL_DYNAMIC_ENABLE=1`.

In a single-instance configuration, this function sets the log level for the instance.

<br />

In a multi-instance configuration (`OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE`), if `OPENTHREAD_CONFIG_LOG_INSTANCE_AWARE_API_ENABLE` is not enabled, this function returns `OT_ERROR_NOT_CAPABLE`. When the log level is explicitly set on an instance, it overrides the global log level set using `https://openthread.io/reference/group/api-logging#group__api-logging_1gad2468bc293c95479e21b449261e3c73b`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aLogLevel` | The log level. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully updated the log level. | | `OT_ERROR_INVALID_ARGS` | Log level value is invalid. | | `OT_ERROR_NOT_CAPABLE` | Instance-aware logging is not enabled in a multi-instance configuration. | |

## Macros

### OT_LOG_HEX_DUMP_LINE_SIZE

```
 OT_LOG_HEX_DUMP_LINE_SIZE 73
```
Hex dump line string size.

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).