Structured Logging Keys

Liquibase uses a Mapped Diagnostic Context (MDC) to generate structured logs in a JSON format. The output is a nested group of key-value pairs. You can access data from your structured logs by calling on the keys described on this page.

Most values in the log are strings. Other JSON types such as arrays and integers are used for some nested keys.

In Liquibase 4.23.2+, you can create a custom metadata file that controls exactly which keys appears in your Structured Logs. For more information, see Custom and Private Data in Structured Logs.

System keys

The following keys can appear in all structured logs, regardless of which command the log originates from:

Key Description
class Liquibase Java class associated with log event
changelog Name of the changelog associated with the log event
changesetAuthor Value of --author. Author of the changeset being logged
changesetCount Number of changesets associated with the log event
changesetId Value of --id. ID of the changeset being logged
changesetOutcome Outcome of deploying this changeset
deploymentId ID of database deployment. Appears in all logs in Liquibase 4.25.0+.
deploymentOutcome Outcome of the database deployment. Appears in all logs in Liquibase 4.25.0+.
deploymentOutcomeCount Number of changesets deployed. Appears in all logs in Liquibase 4.25.0+.
level Value of --log-level. Level of detail of the output.
liquibaseInternalCommand Name of the internal Liquibase operation
liquibaseCatalogName Value of --liquibase-catalog-name. Name of the database catalog. Appears in all logs in Liquibase 4.25.0+.
liquibaseCommandName Name of the command entered in the CLI
liquibaseSchemaName Value of --liquibase-schema-name. Name of the database schema. Appears in all logs in Liquibase 4.25.0+.
liquibaseSystemName System name running Liquibase
liquibaseSystemUser Name of user running Liquibase
liquibaseTargetUrl URL of the target database associated with the log
liquibaseVersion Version of Liquibase installed
message Short descriptor of log event
operationStart UTC timestamp of operation start
operationStop UTC timestamp of operation end
rowsAffected Number of rows in a table the change affects
thread Thread being used
timestamp UTC timestamp of log event

changelog-sync

Keys that can appear in a changelog-sync structured log:

Key Description
changelogFile The changelog being synced
changelogSyncOutcome Whether the sync was executed or failed
changesetSyncCount Number of changesets added to the DATABASECHANGELOG table
changesetFilepath Path to changeset. Repeats in every changeset log message
changesetContext Context applied to changeset. Repeats in every changeset log message
changesetLabel Label applied to changeset. Repeats in every changeset log message
changesetOperationStart UTC timestamp of operation start. Repeats in every changeset log message
changesetOperationStop UTC timestamp of operation end. Repeats in every changeset log message
changesetSyncOutcome Outcome of changeset sync. Repeats in every changeset log message
databaseChangelogSql SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome Outcome of update to the DATABASECHANGELOG table

diff

Keys that can appear in a diff and/or diff-changelog structured log:

Key Command Description
diffOutcome diff Whether the diff was successful
diffResultsSummary diff

Diff result info. Contains nested keys:

  • changed
    • count
  • missing
    • count
  • unexpected
    • count
format diff Value of --format
outputFile diff Value of --output-file
schema diff Value of --schemas
diffTypes diff, diff-changelog Value of --diff-types
excludeObjects diff, diff-changelog Value of --exclude-objects
includeObjects diff, diff-changelog Value of --include-objects
liquibaseReferenceUrl diff, diff-changelog Value of --reference-url
outputSchemas diff, diff-changelog Value of --output-schemas
referenceDefaultCatalogName diff, diff-changelog Value of --reference-default-catalog-name
referenceDefaultSchemaName diff, diff-changelog Value of --reference-default-schema-name
referenceSchemas diff, diff-changelog Value of --reference-schemas
referenceUsername diff, diff-changelog Value of --reference-username
changesetComment diff-changelog Comment applied to changeset
changesetLabel diff-changelog Label applied to changeset
commandContextFilter diff-changelog Value of --contextFilter
commandLabelFilter diff-changelog Value of --labelFilter
databaseChangelogSql diff-changelog SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome diff-changelog Outcome of update to the DATABASECHANGELOG table
diffChangelogFile diff-changelog <path/to/the/generated/changelog>
includeCatalog diff-changelog Value of --include-catalog
includeSchema diff-changelog Value of --include-schema
includeTablespace diff-changelog Value of --include-tablespace
schemas diff-changelog Value of the --schemas property

flow

Keys that can appear in Structured Logs for the flow command:

Key Description
changelogFile The changelog file you are using with the flow command
commandContextFilter Value of --context-filter
commandLabelFilter Value of --label-filter
rollbackOnError  

history

Keys that can appear in a Structured Log for the history command:

Key Description
changelogPath Path to the changelog you are using with the history command
changesets  
history  
updateDate Date of last deployment

rollback

Keys that can appear in a structured log for commands in the rollback* family. For information about the commands, see rollback, rollback-count, rollback-one-changeset, rollback-one-update, and rollback-to-date.

Key Command Description
changelogFile rollback* The changelog containing changesets being rolled back
changesetComment rollback* Comment applied to changeset
changesetLabel rollback* Label applied to changeset
changesetOperationStart rollback* UTC timestamp of operation start. Repeats in every changeset log message
changesetOperationStop rollback* UTC timestamp of operation end. Repeats in every changeset log message
changesetOutcome rollback* Individual changeset outcomes
changesetSql rollback* Generated/executed SQL
changesetsRolledBack rollback*

The changesets that were rolled back. Contains nested keys:

  • changesetCount
  • changeset
    • changesetAuthor
    • changesetFilepath
    • changesetId
    • changesetOutcome
    • deploymentId
commandContextFilter rollback* Value of --context-filter
commandLabelFilter rollback* Value of --label-filter
databaseChangelogSql rollback* SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome rollback* Outcome of update to the DATABASECHANGELOG table
rollbackCount rollback-count Value of --count in rollback-count logs only
rollbackDate rollback-to-date Value of --date in rollback-date logs only
rollbackOneChangesetForce rollback-one-changeset Value of --force in rollback-one-changeset logs only
rollbackOneUpdateForce rollback-one-update Value of --force in rollback-one-update logs only
rollbackScript rollback* Value of --rollback-script
rollbackToTag rollback Value of --tag

status

Keys that can appear in a Structured Log for the status command:

Key Description
changelogFile The changelog potentially containing undeployedchangesets
commandContextFilter Value of --context-filter
commandLabelFilter Value of --label-filter

update

Keys that can appear in structured log for commands in the update* family. For information about the commands, see update, update-count, update-one-changeset, update-testing-rollback, and update-to-tag.

Key Command Description
changelogFile update* The changelog containing changesets being deployed
changesetComment update* Comment applied to changeset
changesetLabel update* Label applied to changeset
changesetOperationStart update* UTC timestamp of operation start. Repeats in every changeset log message
changesetOperationStop update* UTC timestamp of operation end. Repeats in every changeset log message
changesetSql update* Generated/executed SQL
changesetsUpdated update*

The changesets that were updated. Contains nested keys:

  • changesetCount
  • changeset
    • changesetAuthor
    • changesetFilepath
    • changesetId
    • changesetOutcome
    • deploymentId
commandContextFilter update* Value of --context-filter
commandLabelFilter update* Value of --label-filter
databaseChangelogSql update* SQL to update the DATABASECHANGELOG table
databaseChangelogTableOutcome update* Outcome of update to the DATABASECHANGELOG table
rollbackOnError update* Value of --rollback-on-error
updateSummary update*

Only if --show-summary=summary. Contains nested keys:

  • value
  • run
  • runPreviously
  • skipped
    • dbmsUnknown
    • labels
    • context
    • totalSkipped
  • totalChangesets

version

Keys that can appear in a Structured Log for the version global argument:

Key Description
javaHome

Contains nested keys:

  • path
  • version
liquibaseLibraries

Contains nested keys:

libraries

  • "name": "Apache Commons Collections",
    "path": "internal/lib/commons-collections4.jar"
  • "name": "Apache Commons Lang",
    "path": "internal/lib/commons-lang3.jar"
  • "name": "Apache Commons Text",
    "path": "internal/lib/commons-text.jar"
  • "name": "H2 Database Engine",

    "path": "internal/lib/h2.jar"
  • "name": "HSQLDB",

    "path": "internal/lib/hsqldb.jar"
  • "name": "jaxb-api",

    "path": "internal/lib/jaxb-api.jar"
  • "name": "JAXB Core",

    "path": "internal/lib/jaxb-core.jar"
  • "name": "JAXB Runtime",

    "path": "internal/lib/jaxb-runtime.jar"
  • "name": "Jaybird",

    "path": "internal/lib/jaybird.jar"
  • "name": "IBM JCC JDBC 4 Driver",

    "path": "internal/lib/jcc.jar"
  • "name": "Commercial Liquibase Functionality",

    "path": "internal/lib/liquibase-commercial.jar"
  • "name": "mariadb-java-client",

    "path": "internal/lib/mariadb-java-client.jar"
  • "name": "Microsoft JDBC Driver for SQL Server",

    "path": "internal/lib/mssql-jdbc.jar"
  • "name": "JDBC",

    "path": "internal/lib/ojdbc8.jar"
  • "name": "opencsv",

    "path": "internal/lib/opencsv.jar"
  • "name": "picocli",

    "path": "internal/lib/picocli.jar"
  • "name": "PostgreSQL JDBC Driver",

    "path": "internal/lib/postgresql.jar"
  • "name": "SnakeYAML",

    "path": "internal/lib/snakeyaml.jar"
  • "name": "snowflake-jdbc",

    "path": "internal/lib/snowflake-jdbc.jar"
  • "name": "SQLite JDBC",

    "path": "internal/lib/sqlite-jdbc.jar"