> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add custom metrics

> Track app-specific events and visualize them on the monitoring dashboard

Every app comes with default metrics for request count, latency, error rate, and workflow activity. You can also define custom metrics to track app-specific events — like task completions, feature usage, or business KPIs.

Custom metrics work by logging structured events from your app code, then configuring `metrics.json` to derive metrics from those events and display them on the monitoring dashboard.

## Log a custom event

Use `log()` from the framework to emit a structured event whenever a task is completed. Add this to the `updateTask` procedure:

```typescript theme={null}
import { log } from '@synthetiq/app-framework/server';

if (input.status === 'completed') {
  log({
    source: 'app',
    type: 'task_completed',
    priority: task.priority,
    userId: ctx.userId,
    traceId: ctx.traceId,
  });
}
```

Every log entry needs a `source` and `type`. Beyond that, you can include any fields you want — these become available for log filtering and metric dimensioning. Logs are searchable in the monitoring dashboard at `/admin/monitoring/logs`.

## Define the metric

Add a `TaskCompleted` metric to `metrics.json` that counts every `task_completed` event, dimensioned by priority:

```json theme={null}
{
  "metrics": [
    ...
    {
      "name": "TaskCompleted",
      "unit": "Count",
      "value": 1,
      "dimensions": ["priority"],
      "filter": { "type": ["task_completed"] }
    }
  ],
  "dimensions": {
    ...
    "priority": {
      "field": "priority",
      "buckets": {
        "High": [4, 5],
        "Medium": [2, 3],
        "Low": [1, 1]
      }
    }
  }
}
```

* `filter` controls which log entries feed into this metric — here, only entries where `type` is `"task_completed"`
* `value: 1` means each matching entry counts as one occurrence
* `dimensions` defines how the metric is sliced — the `priority` dimension buckets the raw numeric priority into High, Medium, and Low

All dimensions must define `buckets` to bound cardinality. Buckets can be numeric ranges (`[min, max]`) or exact string matches.

## Add a chart

Add a chart to visualize task completions on the monitoring dashboard:

```json theme={null}
{
  "charts": [
    ...
    {
      "title": "Task Completions by Priority",
      "metric": "TaskCompleted",
      "stat": "Sum",
      "chartType": "bar",
      "splitBy": "priority",
      "tab": "custom metrics"
    }
  ]
}
```

This creates a new **Custom Metrics** tab on the monitoring dashboard at `/admin/monitoring/dashboard` with a stacked bar chart showing task completions split by priority level. You can add more charts to the same tab by using the same `tab` value.

For production monitoring, dashboard configuration, and the observability API, see [Monitoring](/docs/platform-docs/deployments/monitoring/metrics). For the full `metrics.json` schema, default metrics, and chart options, see the [Metrics reference](/docs/platform-docs/app-framework/reference/metrics).