Reporting deploys to track improvements

How your application functions can change with each new deployment. When tracking your deploys with AppSignal, error incidents and performance measurements are grouped per deployment, so you can easily see what impacts your deployment has had on your application’s performance and error rate. AppSignal can take you from an error backtrace to the line of code from which a specific error originated, and this help This guide will show you how to track deploys in AppSignal using deploy markers.

Read more in-depth information about deploy markers and what they’re used for.

Configuring AppSignal

This guide will use the revision config option method of reporting deploy markers. You can read about alternative approaches to this in our Deploy Markers documentation. The revision config option is configured differently per integration language. See the list of integrations below for the one your app uses. Note that AppSignal will automatically report a deploy when using platforms such as Heroku or Render, or deployment orchestrators such as Kamal.

Automatically Update the Revision

We recommend dynamically fetching the revision config option value from the source control management used for your project (such as Git or SVN) on start or deploy. This way, the value doesn’t have to be manually updated per deploy. If a Git commit hash is used, it will also be compatible with error backtrace links. Below is an example of how you would do this using Git:

git rev-parse --short HEAD
# Will output the current commit's short SHA

We’ll continue to use Git for all integration examples in this documentation.

Ruby

For Ruby applications we will load the Git revision from the config file. The shell command that we run in the revision configuration option is the same command we used previously to retrieve the hash of the current commit. We call the git rev-parse command and set the output as the revision config option, as shown in the example below:

Appsignal.configure do |config|
  config.revision = `git rev-parse --short HEAD`.strip
end

Using Ruby deploy gems

If you use a deployment tool like Capistrano or Hatchbox that excludes the .git folder from getting deployed:

Modify the deploy process to run a command that creates a REVISION file in the current folder which contains the Git hash: git rev-parse --short HEAD > REVISION

When using a Platform-as-a-Service provider, the provider might create this file for you, or expose the revision as an environment variable that you can read from the configuration file. If you are unsure if this applies to you, check with your provider or get in touch, we may know the answer. Below is an example of how to read the Git hash from a REVISION file when using Rails:

Appsignal.configure do |config|
  revision = Rails.root.join("REVISION") if defined?(Rails)
  config.revision = revision.read.strip[0, 7] if revision&.exist?
end

Elixir

For Elixir applications we will load the Git revision in the config/appsignal.exs config file (your file location may differ). In the example config/appsignal.exs file below, we call the git rev-parse command with Elixir and set the output as the revision config option.

# Example: config/appsignal.exs
{revision, _exitcode} = System.cmd("git", ["log", "--pretty=format:%h", "-n 1"])
config :appsignal, :config,
  revision: revision
  # Other config options

Node.js

For Node.js applications, the Git revision is loaded in the app’s config file. In the below .js snippet we call the git rev-parse command with Node.js and set the output as the revision config option.

// Example: appsignal.js
const childProcess = require("child_process");
const REVISION = childProcess.execSync("git rev-parse --short HEAD").toString();
const appsignal = new Appsignal({
  revision: REVISION,
  // Other config
});

module.exports = { appsignal };

Python

For Python applications, the Git revision is loaded in the application’s __appsignal__.py config file. In the example below, we call the git rev-parse command with Python and set the output as the revision config option. The shell command that we run is the same command we used previously to retrieve the hash of the current commit.

# Example: __appsignal__.py
import subprocess
from appsignal import Appsignal

revision = subprocess.check_output(
    "git rev-parse --short HEAD", shell=True, text=True
).strip()

appsignal = Appsignal(
    # Other config
    revision=revision
)

Front-end JavaScript

Because Front-end JavaScript applications run in-browser, it is not possible to call the git executable command from your front-end application to get the current revision. There are two common approaches to pass the revision value to your front-end application:

Using build-time environment variables (recommended for decoupled front-ends)

Modern front-end build tools embed environment variables into your bundle at build time. You can pass the Git revision through one of these variables and reference it in your AppSignal config. The variable prefix and access pattern depend on your build tool. The example below uses Vite, which exposes environment variables prefixed with VITE_ through the import.meta.env object. Set the variable before building:

export VITE_REVISION=$(git rev-parse --short HEAD)
npm run build

Then read it in the file where you configure AppSignal:

// Example: appsignal.js
export const appsignal = new Appsignal({
  revision: import.meta.env.VITE_REVISION,
  // Other config
});

Import the configured appsignal instance wherever you initialize your app. For example, in a Vue application’s main.js:

// Example: main.js
import { createApp } from "vue";
import App from "./App.vue";
import { appsignal } from "./appsignal";
import { errorHandler } from "@appsignal/vue";

const app = createApp(App);
app.config.errorHandler = errorHandler(appsignal, app);

app.mount("#app");

Using a back-end rendered HTML attribute

If your front-end is rendered by a back-end application (such as a Ruby or Elixir application), you can define the revision value in the HTML body as a data attribute:

<body data-app-revision="REVISION VALUE">
  <!-- Rest of the HTML -->
</body>

Then retrieve this value in your JavaScript:

// Example: appsignal.js
const body = document.body;
export const appsignal = new Appsignal({
  revision: body.dataset.appRevision,
  // Other config
});

Go

For Go applications, the revision is set on an OpenTelemetry resource attribute when OpenTelemetry is initialized. In the example below, we call the git rev-parse command and set the output as the appsignal.config.revision resource attribute. The shell command that we run is the same command we used previously to retrieve the hash of the current commit.

import (
	"os/exec"

	// And other imports
)

var revision string
cmd := exec.Command("git", "rev-parse", "--short", "HEAD")
output, err := cmd.Output()
if err != nil {
	revision = "unknown"
} else {
	revision = strings.TrimSpace(string(output))
}

res := resource.NewWithAttributes(
	resource.WithAttributes(attribute.String("appsignal.config.revision", revision)),
	// And other resource attributes
)

For Go applications the appsignal.config.revision config option is required configuration, so it should already be set. Please consult the appsignal.config.revision config option for more information.

Java

For Java applications, set the revision using the OTEL_RESOURCE_ATTRIBUTES environment variable. We’ll use the same Git command as shown previously.

export OTEL_RESOURCE_ATTRIBUTES="\
  appsignal.config.revision=$(git rev-parse --short HEAD),\
  ..."

For Java applications the appsignal.config.revision config option is required configuration, so it should already be set. Please consult the appsignal.config.revision config option for more information.

PHP

For PHP applications, set the revision in your configuration to override the default. By default, AppSignal sets the revision using the same Git command shown in Automatically update the revision.

$revision = trim(shell_exec('git rev-parse --short HEAD 2>/dev/null')) ?: 'unknown';

return [
    'revision' => $revision,
    // ... other options
];

Please consult the appsignal.config.revision config option for more information.

Deploy

When finished configuring the revision option, commit your changes and deploy your application. When the app starts/restarts, AppSignal will create a deploy in the deploys section for your app. That’s it! You’ve successfully configured your application to notify AppSignal of deploys! Your application’s data will be tracked alongside the appropriate deployment, helping level up your ability to analyze your application’s performance. Are deploys not being reported or incorrectly? Contact us and we will help you out!

​Configuring AppSignal

​Automatically Update the Revision

​Configurations per Language

​Ruby

​Using Ruby deploy gems

​Elixir

​Node.js

​Python

​Front-end JavaScript

​Using build-time environment variables (recommended for decoupled front-ends)

​Using a back-end rendered HTML attribute

​Go

​Java

​PHP

​Deploy

Configuring AppSignal

Automatically Update the Revision

Configurations per Language

Ruby

Using Ruby deploy gems

Elixir

Node.js

Python

Front-end JavaScript

Using build-time environment variables (recommended for decoupled front-ends)

Using a back-end rendered HTML attribute

Go

Java

PHP

Deploy