What data does Liquibase collect and how is it used?

Why collect analytics?

Gathering anonymous usage analytics allows us to better understand how Liquibase is actually being used by a diverse set of millions of users. This data helps our small team help our users better by providing insight into things like:

• Which commands are the most used: if some commands are never used it might mean we need to reconsider that command’s purpose, provide more resources to help increase usage, or even remove the command entirely.

• Which commands result in the most failures: knowing this helps us identify gaps in documentation or the product itself.

• Which database platforms are the most used with Liquibase: this information helps us identify where we should focus our efforts to maximize benefit for our users.

• Which versions of Java are our users on: this helps us as we consider updating Java versions in core and many extensions.

• Which versions of Liquibase are users on: this helps us understand if users are updating regularly or where we might help with updates.

What information do we collect?

If analytics are enabled, Liquibase records the following information when a command is run:

• Command-specific data like command name, if the command succeeded or failed, and exception data if there is a failure

• Liquibase data including version and interface that it’s being run in

• Database platform including version

• Changelog formats and number of changelogs run

• Extension information like which extensions are being used and what version

• Liquibase Secure feature information like which features are enabled

• Operating system information like type of OS, version, and architecture

Liquibase does not gather any personally identifiable information. This data is all aggregated and anonymous.

To see a log of analytics data collected when you run a command, set both --log-level and --analytics-log-level to FINE. There is a JSON object at the end of the output containing the analytics for the command.

Do analytics affect Liquibase performance?

Analytics do not significantly affect Liquibase performance. Enabling or disabling analytics does not change your experience of Liquibase.

Liquibase processes analytics after running a command. Although analytics are typically processed more quickly, Liquibase waits a maximum of 1.5 seconds for them to finish processing after running a command. If Liquibase cannot process analytics data within 1.5 seconds, it continues with the operation.

Opt out

If you do not want to participate in Liquibase anonymous analytics, you can opt out at any time using the --analytics-enabled parameter.

• Opt out per CLI command: specify the parameter --analytics-enabled=false. This turns off analytics gathering for that single occurrence of a command. For example:

• liquibase --analytics-enabled=false status

• Opt out globally: add liquibase.analytics.enabled: false to your defaults file or use the environment variable LIQUIBASE_ANALYTICS_ENABLED=false.

Opt in

If you have previously disabled Liquibase anonymous analytics, you can opt in at any time using the --analytics-enabled parameter.

• Opt in per CLI command: specify the parameter --analytics-enabled=true. This turns on analytics gathering for that single occurrence of a command. For example:

• liquibase --analytics-enabled=true status

• Opt in globally: add liquibase.analytics.enabled: true to your defaults file or use the environment variable LIQUIBASE_ANALYTICS_ENABLED=true.

Validating your selection

You can verify whether anonymous analytics are being collected by setting an analytics log level and then querying for status.

For example, to see whether you've successfully disabled analytics, you could set the analytics log level to INFO and query whether the Liquibase analytics is set to false.

liquibase --analytics-log-level INFO --analytics-enabled false status --log-level INFO

If analytics is disabled, the log will return: INFO [liquibase.analytics] User has disabled analytics.

Troubleshooting

If you use an external application that blocks analytics at the DNS level and causes your application to fail, you can do one of the following:

• Use the --analytics-enabled parameter to turn off analytics.

• Whitelist the domain your external application is blocking