Skip to main content
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: 
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: 
{
  "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: 
{
  "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. For the full metrics.json schema, default metrics, and chart options, see the Metrics reference.