App metrics in third-party tools

App metrics, which can be viewed in the developer console, show you how your Forge app is currently performing across all sites.

You can also use our Export metrics API to export these app metrics to several monitoring tools, including SignalFX and Datadog. These tools offer capabilities, like grouping and filtering metrics by different attributes and integrating with incident response tools.

The Export metrics API is an Atlassian GraphQL metrics API that provides metrics in the OTLP protobuf JSON format, which is the format used in the OpenTelemetry framework.

This page explains the OpenTelemtry framework and how to authenticate with the Atlassian GraphQL Gateway, which will help prepare for exporting your Forge app metrics to a third-party monitoring tool of your choice.

OpenTelemetry framework

OpenTelemetry is an observability framework and toolkit designed to create and manage telemetry data, such as traces, metrics, and logs.

The OpenTelemetry Protocol (OTLP) specification describes the encoding, transport, and delivery mechanism of telemetry data between telemetry sources and intermediate nodes, such as collectors and telemetry backends.

The OpenTelemetry Collector (OTEL) offers a vendor-agnostic implementation of how to receive, process, and export telemetry data. It removes the need to run, operate, and maintain multiple agents or collectors. This works with improved scalability and supports open source observability data formats, such as Jaeger, Prometheus, Fluent Bit, and more, sending to one or more open source or commercial backends.

Authentication with the Atlassian GraphQL Gateway

You must first authenticate with the Atlassian GraphQL Gateway (AGG) to consume the Export metrics API and export app metrics to a tool of your choice.

To get started using basic authentication:

1. Go to https://id.atlassian.com/manage/api-tokens.
2. Select Create API token.
3. Enter a label to describe your API token. For example, export-metrics-api-token.
4. Select Create.
5. Select Copy to clipboard and close the dialog.
6. Include the token and your email in the header of your GraphQL request.
7. Pass the X-ExperimentalAPI header. This is because the API is still in the experimental phase and is subject to change.
8. Provide a custom User-Agent header. This helps differentiate traffic coming from the developer console and your own export service. We recommend using this value: ForgeMetricsExportServer/1.0.0

Now you're ready to start exporting your Forge app metrics.