---
title: "Migrate from Promtail to Grafana Alloy | Grafana Alloy documentation"
description: "Learn how to migrate from Promtail to Grafana Alloy"
---

# Migrate from Promtail to Grafana Alloy

The built-in Alloy convert command can migrate your [Promtail](https://www.grafana.com/docs/loki/latest/clients/promtail/) configuration to an Alloy configuration.

This topic describes how to:

- Convert a Promtail configuration to an Alloy configuration.
- Run a Promtail configuration natively using Alloy.

## Components used in this topic

- [`local.file_match`](../../../reference/components/local/local.file_match/)
- [`loki.source.file`](../../../reference/components/loki/loki.source.file/)
- [`loki.write`](../../../reference/components/loki/loki.write/)

## Before you begin

- You must have a Promtail configuration.
- You must be familiar with the concept of [Components](../../../get-started/components/) in Alloy.

## Convert a Promtail configuration

To fully migrate from [Promtail](https://www.grafana.com/docs/loki/latest/clients/promtail/) to Alloy, you must convert your Promtail configuration into an Alloy configuration. This conversion allows you to take full advantage of the many additional features available in Alloy.

> In this task, you use the [convert](../../../reference/cli/convert/) CLI command to output an Alloy configuration from a Promtail configuration.

1. Open a terminal window and run the following command.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy convert --source-format=promtail --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
   ```
   
   Replace the following:
   
   - *`<INPUT_CONFIG_PATH>`* : The full path to the Promtail configuration.
   - *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.
2. [Run](../../../reference/cli/run/) Alloy using the new configuration from *`<OUTPUT_CONFIG_PATH>`* :

### Debugging

1. If the convert command can’t convert a Promtail configuration, diagnostic information is sent to `stderr`. You can bypass any non-critical issues and output the Alloy configuration using a best-effort conversion by including the `--bypass-errors` flag.
   
   > Caution
   > 
   > If you bypass the errors, the behavior of the converted configuration may not match the original Promtail configuration. Make sure you fully test the converted configuration before using it in a production environment.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy convert --source-format=promtail --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
   ```
   
   Replace the following:
   
   - *`<INPUT_CONFIG_PATH>`* : The full path to the Promtail configuration.
   - *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.
2. You can also output a diagnostic report by including the `--report` flag.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy convert --source-format=promtail --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
   ```
   
   Replace the following:
   
   - *`<INPUT_CONFIG_PATH>`* : The full path to the Promtail configuration.
   - *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.
   - *`<OUTPUT_REPORT_PATH>`* : The output path for the report.
   
   If you use the [example](#example) Promtail configuration below, the diagnostic report provides the following information:
   
   plaintext ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```plaintext
   (Warning) If you have a tracing set up for Promtail, it cannot be migrated to Alloy automatically. Refer to the documentation on how to configure tracing in Alloy.
   (Warning) The metrics from Alloy are different from the metrics emitted by Promtail. If you rely on Promtail's metrics, you must change your configuration, for example, your alerts and dashboards.
   ```

## Run a Promtail configuration

If you’re not ready to completely switch to an Alloy configuration, you can run Alloy using your Promtail configuration. The `--config.format=promtail` flag tells Alloy to convert your Promtail configuration to Alloy and load it directly without saving the new configuration. This allows you to try Alloy without modifying your Promtail configuration infrastructure.

> In this task, you use the [run](../../../reference/cli/run/) CLI command to run Alloy using a Promtail configuration.

[Run](../../../reference/cli/run/) Alloy and include the command line flag `--config.format=promtail`. Your configuration file must be a valid Promtail configuration file rather than an Alloy configuration file.

### Debug

1. You can follow the convert CLI command [debugging](#debugging) instructions to generate a diagnostic report.
2. Refer to the Alloy [Debugging](../../../troubleshoot/debug/) for more information about running Alloy.
3. If your Promtail configuration can’t be converted and loaded directly into Alloy, diagnostic information is sent to `stderr`. You can bypass any non-critical issues and start Alloy by including the `--config.bypass-conversion-errors` flag in addition to `--config.format=promtail`.
   
   > Caution
   > 
   > If you bypass the errors, the behavior of the converted configuration may not match the original Promtail configuration. Don’t use this flag in a production environment.

## Example

This example demonstrates converting a Promtail configuration file to an Alloy configuration file.

The following Promtail configuration file provides the input for the conversion.

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
clients:
  - url: http://localhost/loki/api/v1/push
scrape_configs:
  - job_name: example
    static_configs:
      - targets:
          - localhost
        labels:
          __path__: /var/log/*.log
```

The convert command takes the YAML file as input and outputs an [Alloy configuration](../../../get-started/configuration-syntax/) file.

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy convert --source-format=promtail --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```

Replace the following:

- *`<INPUT_CONFIG_PATH>`* : The full path to the Promtail configuration.
- *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.

The new Alloy configuration file looks like this:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
local.file_match "example" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/*.log",
  }]
}

loki.source.file "example" {
  targets    = local.file_match.example.targets
  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = "http://localhost/loki/api/v1/push"
  }
  external_labels = {}
}
```

## Limitations

Configuration conversion is done on a best-effort basis. Alloy issues warnings or errors where the conversion can’t be performed.

After the configuration is converted, review the Alloy configuration file created and verify that it’s correct before starting to use it in a production environment.

The following list is specific to the convert command and not Alloy:

- Check if you are using any extra command line arguments with Promtail that aren’t present in your configuration file. For example, `-max-line-size`.
- Check if you are setting any environment variables, whether [expanded in the configuration file](https://www.grafana.com/docs/loki/latest/clients/promtail/configuration/#use-environment-variables-in-the-configuration) itself or consumed directly by Promtail, such as `JAEGER_AGENT_HOST`.
- In Alloy, the positions file is saved at a different location. Refer to the [`loki.source.file`](../../../reference/components/loki/loki.source.file/) documentation for more details. Check if you have any setup, for example, a Kubernetes Persistent Volume, that you must update to use the new positions path.
- Meta-monitoring metrics exposed by Alloy usually match Promtail meta-monitoring metrics but uses a different name. Make sure that you use the new metric names, for example, in your alerts and dashboards queries.
- The logs produced by Alloy differ from those produced by Promtail.
- Alloy exposes the Alloy [UI](../../../troubleshoot/debug/#alloy-ui), which differs from the Promtail Web UI.
- If you are converting a Promtail configuration and not deploying as a Kubernetes daemonset, [modify the generated configuration](../../../reference/components/discovery/discovery.kubernetes/#limit-to-only-pods-on-the-same-node) to ensure `discovery.kubernetes` discovery behaves as expected. The converter makes the same assumption as promtail that any `pod` discovery is for a daemonset deployment.