App observability in third-party tools

App observability provides data that can help understand app performance at any given time, as well as provide access to accurate information about where and why an app may be failing or needing improvement.

You can view and monitor invocation metrics, API metrics, and app logs in the developer console.

You can also choose to export metrics and logs to several observability tools of your choice, including SignalFX and Datadog. Such tools offer capabilities, like grouping and filtering metrics by different attributes and integrating logs with incident response tools.

OpenTelemetry framework

OpenTelemetry is an observability framework and toolkit designed to create and manage telemetry data, such as traces, metrics, and logs. OpenTelemetry uses a standard format for how observability data is collected and sent to tools and services.

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.

Metrics in third-party tools

App metrics show you how your Forge app is currently performing across all sites on which your app is installed.

You can use the App metrics API to export app metrics to several observability tools. The App 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.

Authentication with the Atlassian GraphQL Gateway

You must first authenticate with the Atlassian GraphQL Gateway (AGG) to consume the 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.

Logs in third-party tools

App logs help in tracking down and troubleshooting issues that app users may be experiencing. Forge app owners and app contributors can view app logs.

You can use the App logs API to export app logs to observability tools. The App logs API is a REST API that provides logs in the OTLP log data model (example), which is the format used in the OpenTelemetry framework.

Authentication with the Atlassian Gateway

You must first authenticate with the Atlassian Gateway to consume the API and export app logs to a tool of your choice. For this you need to generate the API tokens to access the App logs API.

To generate the API tokens:

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-logs-api-token.
4. Select Create.
5. Select Copy to clipboard and close the dialog.
6. Use this token as a Basic Authorization when making request to the API.

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