Menu
Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Command-line interfacebreadcrumb arrow convert
Open source

Public preview

The convert command

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. The stability.level flag must be set to public-preview or below to use the component.

The convert command converts a supported configuration format to the Alloy configuration format.

Usage

Usage:

shell 
alloy convert [<FLAG> ...] <FILE_NAME>

Replace the following:

  • <FLAG>: One or more flags that define the input and output of the command.
  • <FILE_NAME>: The Alloy configuration file.

If the <FILE_NAME> argument isn’t provided or if the <FILE_NAME> argument is equal to -, convert converts the contents of standard input. Otherwise, convert reads and converts the file from disk specified by the argument.

There are several different flags available for the convert command. You can use the --output flag to write the contents of the converted configuration to a specified path. You can use the --report flag to generate a diagnostic report. The --bypass-errors flag allows you to bypass any errors generated during the file conversion.

The command fails if the source configuration has syntactically incorrect configuration or can’t be converted to an Alloy configuration.

The following flags are supported:

  • --output, -o: The filepath and filename where the output is written.
  • --report, -r: The filepath and filename where the report is written.
  • --source-format, -f: Required. The format of the source file. Supported formats: otelcol, prometheus, promtail, static.
  • --bypass-errors, -b: Enable bypassing errors when converting.
  • --extra-args, e: Extra arguments from the original format used by the converter.

Defaults

Alloy defaults are managed as follows:

  • If a provided source configuration value matches an Alloy default value, the property is left off the output.
  • If a non-provided source configuration value default matches an Alloy default value, the property is left off the output.
  • If a non-provided source configuration value default doesn’t match an Alloy default value, the default value is included in the output.

Errors

Errors are defined as non-critical issues identified during the conversion where an output can still be generated. These can be bypassed using the --bypass-errors flag.

OpenTelemetry Collector

You can use the --source-format=otelcol to convert the source configuration from an OpenTelemetry Collector to a Alloy configuration.

Many OpenTelemetry Collector components are supported. Review the otelcol.* component information in the [Component Reference][] for more information about otelcol components that you can convert. If a source configuration has unsupported features, you will receive errors when you convert it to an Alloy configuration. The converter raises warnings for configuration options that may require your attention.

Refer to Migrate from OpenTelemetry Collector to Alloy for a detailed migration guide.

Prometheus

Using the --source-format=prometheus will convert the source configuration from Prometheus v2.45 to an Alloy configuration.

This includes Prometheus features such as scrape_config, relabel_config, metric_relabel_configs, remote_write, and many supported *_sd_configs. Unsupported features in a source configuration result in errors.

Refer to Migrate from Prometheus to Alloy for a detailed migration guide.

Promtail

Using the --source-format=promtail will convert the source configuration from Promtail v2.8.x to an Alloy configuration.

Nearly all Promtail features are supported and can be converted to Alloy configuration.

If you have unsupported features in a source configuration, you will receive errors when you convert to an Alloy configuration. The converter will also raise warnings for configuration options that may require your attention.

Refer to Migrate from Promtail to Alloy for a detailed migration guide.

Static

Using the --source-format=static will convert the source configuration from a Grafana Agent Static configuration to an Alloy configuration.

Include --extra-args for passing additional command line flags from the original format. For example, --extra-args="-enable-features=integrations-next" converts a Grafana Agent Static integrations-next configuration to an Alloy configuration. You can also expand environment variables with --extra-args="-config.expand-env". You can combine multiple command line flags with a space between each flag, for example --extra-args="-enable-features=integrations-next -config.expand-env".

If you have unsupported features in a Grafana Agent Static mode source configuration, you will receive errors when you convert to an Alloy configuration. The converter also raises warnings for configuration options that may require your attention.

Refer to Migrate from Grafana Agent Static to Alloy for a detailed migration guide.