Audit Log

ThingsBoard provides audit log functionality to track user actions on the main platform entities: assets, devices, dashboards, rules, and more. Tenant administrators can use audit logs to monitor activity, investigate incidents, and maintain security and compliance records.

Viewing audit logs

Tenant administrators can access audit logs from the Audit logs page in the left-hand menu. The interface provides the following capabilities:

Date range — filter audit log entries by a custom time period.
Full-text search — search within fetched entities to find specific entries.
Details — click the details button on any entry to view the full low-level information about the logged action.

REST API

Audit logs are accessible programmatically via the REST API. Available calls allow fetching entries related to a specific user, entity, or customer, or retrieving all records using page links.

Refer to the REST API reference for the full list of audit log endpoints.

Configuration

System administrators configure audit logging in `thingsboard.yml`. The configuration controls whether logging is enabled, how data is partitioned for storage, which entity types are logged, and at what level.

# Audit log parameters
audit_log:
  # Enable/disable audit log functionality.
  enabled: "${AUDIT_LOG_ENABLED:true}"
  # Specify partitioning size for audit log by tenant id storage. Example MINUTES, HOURS, DAYS, MONTHS
  by_tenant_partitioning: "${AUDIT_LOG_BY_TENANT_PARTITIONING:MONTHS}"
  # Number of days as history period if startTime and endTime are not specified
  default_query_period: "${AUDIT_LOG_DEFAULT_QUERY_PERIOD:30}"
  # Logging levels per each entity type.
  # Allowed values: OFF (disable), W (log write operations), RW (log read and write operations)
  logging_level:
    mask:
      "device": "${AUDIT_LOG_MASK_DEVICE:W}"
      "asset": "${AUDIT_LOG_MASK_ASSET:W}"
      "dashboard": "${AUDIT_LOG_MASK_DASHBOARD:OFF}"
      "customer": "${AUDIT_LOG_MASK_CUSTOMER:W}"
      "user": "${AUDIT_LOG_MASK_USER:RW}"
      "rule": "${AUDIT_LOG_MASK_RULE:RW}"
      "plugin": "${AUDIT_LOG_MASK_PLUGIN:RW}"
  sink:
    # Type of external sink. possible options: none, elasticsearch
    type: "${AUDIT_LOG_SINK_TYPE:none}"
    # Name of the index where audit logs stored
    # Index name could contain next placeholders (not mandatory):
    # @{TENANT} - substituted by tenant ID
    # @{DATE} - substituted by current date in format provided in audit_log.sink.date_format
    index_pattern: "${AUDIT_LOG_SINK_INDEX_PATTERN:@{TENANT}_AUDIT_LOG_@{DATE}}"
    # Date format. Details of the pattern could be found here:
    # https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html
    date_format: "${AUDIT_LOG_SINK_DATE_FORMAT:YYYY.MM.DD}"
    scheme_name: "${AUDIT_LOG_SINK_SCHEME_NAME:http}" # http or https
    host: "${AUDIT_LOG_SINK_HOST:localhost}"
    port: "${AUDIT_LOG_SINK_POST:9200}"
    user_name: "${AUDIT_LOG_SINK_USER_NAME:}"
    password: "${AUDIT_LOG_SINK_PASSWORD:}"

Configuration parameters

enabled · AUDIT_LOG_ENABLED · Default true

Enables or disables audit log functionality.

by_tenant_partitioning · AUDIT_LOG_BY_TENANT_PARTITIONING · Default MONTHS

Storage partition size per tenant. Supported values: MINUTES, HOURS, DAYS, MONTHS.

default_query_period · AUDIT_LOG_DEFAULT_QUERY_PERIOD · Default 30

Number of days used as the history period when no startTime and endTime are specified in a query.

Logging levels

The logging_level.mask section controls which entity types are logged and at what level:

Level	Description
`OFF`	Logging disabled for this entity type.
`W`	Log write operations only (create, update, delete).
`RW`	Log both read and write operations.

Default configuration logs write operations for devices, assets, and customers; disables logging for dashboards; and logs read and write operations for users, rules, and plugins.

External log sink

Audit logs can be forwarded to an external system such as Elasticsearch. Configure the `sink` section to enable this:

type · AUDIT_LOG_SINK_TYPE · Default none

Sink type. Supported values: none, elasticsearch.

index_pattern · AUDIT_LOG_SINK_INDEX_PATTERN · Default @{TENANT}_AUDIT_LOG_@{DATE}

Index name pattern. Supports @{TENANT} (tenant ID) and @{DATE} (current date) placeholders.

date_format · AUDIT_LOG_SINK_DATE_FORMAT · Default YYYY.MM.DD

Date format for the @{DATE} placeholder. Uses Java DateTimeFormatter patterns.

scheme_name · AUDIT_LOG_SINK_SCHEME_NAME · Default http

Connection scheme: http or https.

host · AUDIT_LOG_SINK_HOST · Default localhost

Elasticsearch host address.

port · AUDIT_LOG_SINK_PORT · Default 9200

Elasticsearch port.

user_name · AUDIT_LOG_SINK_USER_NAME · Default (empty)

Authentication username.

password · AUDIT_LOG_SINK_PASSWORD · Default (empty)

Authentication password.