Skip to main content
Version: Next

Grafana Alloy Migration Guide

This guide provides detailed information on the transition from Promtail to Grafana Alloy within the SmoothGlue platform, including steps for migrating custom Promtail configurations. This migration is a key part of the SmoothGlue 6.16 release and becomes fully integrated by SmoothGlue 6.18.

Background​

The landscape of telemetry collection is constantly evolving, and to ensure SmoothGlue remains at the forefront of observability, we are transitioning from Promtail to Grafana Alloy.

Key Drivers for this Migration:

  • Promtail Deprecation: Promtail will no longer be supported after Big Bang 3.05 (as noted in Big Bang 2.50.0 releases). It is considered feature-complete and is now in Long Term Support (LTS), meaning no new features will be added.

  • Future Development in Alloy: All future development work for logs collection within the Grafana ecosystem will be focused on Grafana Alloy.

  • Enhanced Capabilities with Alloy:

    • Unified Telemetry: Alloy is the preferred agent for collecting and forwarding telemetry data to Grafana Loki, and importantly, it is an open-source distribution of the OpenTelemetry Collector. This means Alloy supports a broader range of telemetry signals, including metrics, logs, traces, and profiles, with a single agent.
    • Reduced Operational Overhead: By unifying telemetry collection, Alloy simplifies deployment and management compared to maintaining separate agents for different signal types.
    • OpenTelemetry Standard: Alloy's adoption of the OpenTelemetry Collector ensures compatibility and alignment with the evolving observability landscape, future-proofing our telemetry collection capabilities.

SmoothGlue's Approach to Alloy Migration​

SmoothGlue automates the default transition from Promtail to Alloy for a seamless upgrade experience. However, if you have custom Promtail configurations, some manual steps are required to ensure these configurations are successfully migrated to Alloy.

What the Platform Operator Needs to Do (and What's Automated)​

Automated by SmoothGlue (No Action Required for Default Configurations)​

When you upgrade to SmoothGlue 6.16 (or later), SmoothGlue will automatically perform the following:

  • Disable Promtail: The Promtail component will be disabled.
  • Enable Alloy: Grafana Alloy will be enabled by default for telemetry collection.

If your SmoothGlue instance uses only the default Promtail configurations, you generally do not need to take any manual action for this migration.

Manual Steps Required for Custom Promtail Configurations​

If your SmoothGlue deployment includes custom configurations for Promtail, you will need to actively migrate these configurations to their equivalent in Grafana Alloy. This is crucial to ensure that your specific logging requirements continue to be met.

To assist with this migration, Grafana Labs provides a migration utility.

Steps for Migrating Custom Promtail Configurations:

  1. Identify Custom Promtail Configurations: Before upgrading to SmoothGlue 6.16, identify any custom scrape_configs or other specific Promtail configurations you have applied. These are typically found in your values.yaml or other configuration files that override default SmoothGlue settings for Promtail.

  2. Utilize the Grafana Alloy Migration Utility: Grafana provides a command-line utility to help convert Promtail configurations to Alloy. This utility can significantly ease the migration process for complex configurations.

    • Installation: You will need to install the Grafana Alloy binary locally to use the promtail-config-convert command. Refer to the official Grafana Alloy documentation for the most up-to-date installation instructions for your operating system.

    Important Considerations:

    • The utility handles common Promtail configurations, but some highly customized or niche features might require manual adjustment.
    • Always review the generated Alloy configuration carefully to ensure it accurately reflects your desired behavior. Pay close attention to target_labels, relabel_configs, and other processing stages.

  3. Integrate Alloy Configuration into SmoothGlue: Once you have your converted alloy-config.alloy file, you will need to integrate it into your SmoothGlue deployment. This typically involves placing the converted configuration within your SmoothGlue values.yaml that customizes the Alloy package.

  4. Perform SmoothGlue Upgrade: After integrating your custom Alloy configuration, proceed with the normal SmoothGlue package deploy procedure to initiate the upgrade to SmoothGlue 6.16 (or higher).

info

See Upgrade SmoothGlue for more detailed steps on general upgrade procedures.

Post-Migration Verification​

After the SmoothGlue upgrade and Alloy deployment, it is critical to verify that your logs and telemetry are being collected and forwarded correctly by Alloy.

  • Check Alloy Pod Logs: Inspect the logs of the Alloy pods in your cluster for any errors or warnings.

    kubectl logs -n <alloy-namespace> <alloy-pod-name>

  • Verify Log Ingestion in Loki: Confirm that your applications' logs are appearing as expected in Grafana Loki.

  • Check Metrics/Traces (if configured): If you've also configured Alloy to collect metrics or traces, verify their ingestion into the respective observability backends (e.g., Prometheus, Tempo).