Monitor custom metrics

Custom metrics allow you to track specific events, actions, and measurements within your Forge app. This enables you to monitor business-specific KPIs and instrument critical paths within your app code.

To view custom metrics:

1. Access the developer console.

2. Select the Forge app that you want to view metrics for.

3. Select Metrics in the left menu.

4. Select Custom in the left menu.

Register a custom metric

To start using custom metrics for your app, you need to register them in the developer console.

To register a custom metric:

1. Select Custom in the left menu under Metrics.

2. Click Register metric.

3. Enter a name and description for your metric. For example, jira-actions-success.

4. Select Register.

Instrument a custom metric

Before proceeding further, ensure you have registered the custom metric for your app already.

1. Install the Forge metrics package by running this command in your terminal:

   1
   2
   npm install @forge/metrics
   

2. Use the metrics package installed above in your app code:

   1
   2
   import { internalMetrics } from '@forge/metrics';
   

3. Implement the custom metrics logic in your code. For example:

   1
   2
   export const run = async (payload, context) => {
     const counter = internalMetrics.counter('jira-actions-success'); // Name should exactly match as registered in developer console
   
     const jiraIssues = await fetch(...);
     counter.incr(); // Increment by 1
     // Or increment by a specific value
     counter.incrBy(value);
     for (const issue of jiraIssues) {
       ....
     }
   };
   

   The metric name in your app code must match the metric name registered in the developer console.

4. Deploy your app using the Forge CLI by running:

   1
   2
   forge deploy
   

5. View the instrumented custom metric in the developer console.

   

Delete a custom metric

Once deleted, custom metric ingestion will be stopped immediately. However, you will still have access to historical data up to 14 days in the past.

To delete a custom metric:

1. Click the options menu next to the metric you want to delete.
2. Select Delete in the menu.
3. Select Delete in the confirmation dialog to confirm.

Filters

Use these filters to refine your metrics:

• Environment: Narrows down the metrics for a specific app environment for your app.

• Date: Narrows down the metrics based on your chosen time interval. Choose from a range of predefined values, such as the Last 24 hours, or choose a more specific time interval using the Custom option.

• Sites: Narrows down the metrics based on the sites that your app is installed onto, for example, <your-site>.atlassian.net. You can select multiple sites.

• Major App Versions: Narrows down the metrics based on the major version of your app.

• Function names: Narrows down the metrics based on the function name from where the custom metric is emitted.

Re-enable custom metrics access

If your user is experiencing problems with your app, but has disabled custom metrics access for their site, you might need them to re-enable custom metrics access.

Give customer the following instructions:

1. Go to admin.atlassian.com.

2. Select the relevant site.

3. Select Apps in the global navigation.

4. In the Sites section of the lefthand navigation, select the site you're administering apps for.

5. In the lefthand navigation, select Connected apps.

6. Select the action button for the app you want to enable custom metrics for.

7. In the Details tab, under Custom metrics access, enable the setting.

   Your user sees a screen like this, showing the details of your app and the controls for enabling or disabling access to their site's custom metrics.