Set Up Metrics

With Sentry Metrics, you can send counters, gauges, distributions, and sets from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.

Requirements

Metrics are supported in Sentry Android SDK version 8.30.0 and above.

Usage

Once the SDK is initialized, you can send metrics using the Sentry.metrics() APIs.

The metrics namespace exposes methods that you can use to capture different types of metric information: count, gauge and distribution.

Counter

Use count to track an incrementing value, such as the number of times a button was clicked or a function was called.

import io.sentry.Sentry;

Sentry.metrics().count("button_click", 1.0);

Gauge

Use gauge to track a value that can go up and down, such as the current memory usage or the number of items in a queue.

import io.sentry.Sentry;

Sentry.metrics().gauge("queue_depth", 42.0);

Distribution

Use distribution to track the distribution of a value, such as the response time of a request.

import io.sentry.Sentry;

Sentry.metrics().distribution("response_time", 187.5);

Adding Attributes

You can also pass additional attributes to any of the metric methods via SentryMetricsParameters. Attributes allow you to filter and group metrics.

import java.util.Map;

import io.sentry.Sentry;
import io.sentry.SentryAttribute;
import io.sentry.SentryAttributes;
import io.sentry.metrics.MetricsUnit;
import io.sentry.metrics.SentryMetricsParameters;

Sentry.metrics().distribution(
  "page_load",
  1.0,
  MetricsUnit.Duration.MILLISECOND,
  SentryMetricsParameters.create(
    Map.of("browser", "Firefox")
  )
);

Sentry.metrics().distribution(
  "response_time",
  1.0,
  MetricsUnit.Duration.MILLISECOND,
  SentryMetricsParameters.create(
    SentryAttributes.of(
      SentryAttribute.stringAttribute("browser", "Firefox")
    )
  )
);

Scope Attributes

You can set attributes on the scope that will be automatically included in all metrics captured within that scope. This is useful for attaching contextual information that should appear on every metric.

import io.sentry.Sentry;
import io.sentry.SentryAttribute;
import io.sentry.SentryAttributes;

// Set a single attribute with automatic type inference
Sentry.setAttribute("request.id", "abc-123");

// Or use a factory method to set the type explicitly
Sentry.setAttribute(SentryAttribute.integerAttribute("request.duration_ms", 150));

// Set multiple attributes at once
Sentry.setAttributes(SentryAttributes.of(
    SentryAttribute.stringAttribute("service", "checkout"),
    SentryAttribute.booleanAttribute("canary", false)
));

// All subsequent metrics will include these attributes
Sentry.metrics().count("order_placed", 1.0);

// Remove an attribute when it's no longer relevant
Sentry.removeAttribute("canary");

Attributes passed directly to a metric call override scope attributes with the same key.

Specifying Units

For gauge and distribution metrics, you can specify a unit using the unit option. This helps Sentry display the metric value in a human-readable format. MetricsUnit offers constants for units supported by Sentry. Sending in custom units is not supported.

import io.sentry.Sentry;
import io.sentry.metrics.MetricsUnit;

Sentry.metrics().distribution(
  "response_time",
  187.5,
  MetricsUnit.Duration.MILLISECOND
);

Sentry.metrics().gauge(
  "memory_usage",
  1024.0,
  MetricsUnit.Information.BYTE
);

Options

The Sentry Android SDK provides several options to configure how metrics are captured and sent to Sentry.

Filtering and Modifying Metrics

Use the getMetrics().beforeSend callback to filter or modify metrics before they're sent to Sentry. This is useful for:

• Removing sensitive data from metric attributes
• Dropping metrics you don't want to send
• Adding or modifying attributes

The callback receives a metric object and must return either a modified metric or null to drop it.

import io.sentry.android.core.SentryAndroid;
import io.sentry.android.core.SentryAndroidOptions;
import io.sentry.SentryAttributeType;
import io.sentry.SentryLogEventAttributeValue;

SentryAndroid.init(context, 
    options -> {
      // ...
      options.getMetrics().setBeforeSend((metric, hint) -> {
        // Drop metrics with specific attributes
        if (metric.getAttributes().containsKey("dropmetric")) {
          return null;
        }

        // Modify metric attributes
        metric.setAttribute("processed", new SentryLogEventAttributeValue(SentryAttributeType.BOOLEAN, true));
        return metric;
      });
    }
);

Disabling Metrics

If you want to disable metrics collection entirely, you can do so by disabling the metrics.enabled flag:

<meta-data
  android:name="io.sentry.metrics.enabled"
  android:value="false"
/>

Default Attributes

By default the SDK will attach the following attributes to a metric:

• environment: The environment set in the SDK if defined. This is sent from the SDK as sentry.environment.
• release: The release set in the SDK if defined. This is sent from the SDK as sentry.release.
• sdk.name: The name of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.name.
• sdk.version: The version of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.version.

User Attributes

If user information is available in the current scope, the following attributes are added to the log:

• user.id: The user ID.
• user.name: The username.
• user.email: The email address.

Replay Attributes

If replay information is available in the current scope, the following attributes are added to the log:

• sentry.replay_id: The ID of the replay.

Scope Attributes

Any attributes set on the current scope via Sentry.setAttribute() or Sentry.setAttributes() are automatically included on all metrics. See Usage above for details.