Metrics reference

Structured logging

Log custom events from the server using the log() function:

import { log } from '@synthetiq/app-framework/server';

log({
  source: 'app',
  type: 'task_completed',
  priority: task.priority,
  userId: ctx.userId,
  traceId: ctx.traceId,
});

Every log entry requires 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.

Client-side logging

Log events from the frontend using the logs.ingest tRPC procedure:

const trpc = getTrpc();

trpc.logs.ingest.mutate({
  type: 'button_clicked',
  traceId: getTraceId(),
  timestamp: Date.now(),
  data: {
    buttonId: 'export',
    page: '/tasks',
  },
});

Field	Type	Required	Description
`type`	string	Yes	Event type identifier
`traceId`	string	Yes	Trace ID from `getTraceId()`
`timestamp`	number	Yes	`Date.now()` at time of event
`path`	string	No	Page path
`method`	string	No	HTTP method
`status`	number	No	Status code
`data`	object	No	Custom fields for metric filtering and dimensioning

The framework automatically sets source: "app" and attaches the authenticated user’s ID.

metrics.json schema

Defined at the app root. Configures how metrics are derived from log entries and how charts are rendered on the monitoring dashboard. Validated at build time.

{
  "metrics": [],
  "dimensions": {},
  "charts": []
}

Metrics

Each metric definition derives a metric from matching log entries:

Field	Type	Required	Description
`name`	string	Yes	Metric name
`unit`	string	Yes	`Count`, `Milliseconds`, `Seconds`, or `Bytes`
`value`	number or string	Yes	A literal number (e.g., `1`) or a log field name to read the value from (e.g., `"ms"`)
`dimensions`	string[]	Yes	Array of dimension keys to group by
`filter`	object	No	Log field → array of accepted values. Only matching log entries contribute to this metric

{
  "name": "TaskCompletions",
  "unit": "Count",
  "value": 1,
  "dimensions": ["priority"],
  "filter": { "type": ["task_completed"] }
}

Dimensions

Dimensions define how metric values are grouped. Each dimension maps a log field to a set of labeled buckets:

Field	Type	Required	Description
`field`	string	Yes	The log field to read
`buckets`	object	No	Label → numeric range `[min, max]` or exact string match

{
  "priority": {
    "field": "priority",
    "buckets": {
      "High": "high",
      "Medium": "medium",
      "Low": "low"
    }
  },
  "statusCategory": {
    "field": "status",
    "buckets": {
      "Success": [200, 399],
      "Warning": [400, 499],
      "Error": [500, 599]
    }
  }
}

Buckets bound cardinality — log values that don’t match any bucket are excluded from that dimension.

Charts

Each chart definition renders a chart on the monitoring dashboard:

Field	Type	Required	Description
`title`	string	Yes	Chart title
`metric`	string	Yes	Metric name to visualize
`stat`	string	No	Statistic type (see below). Defaults to `Sum` for Count, `Average` for other units
`chartType`	string	No	`line` (default) or `bar`
`splitBy`	string	No	Dimension key to split series by. Bar charts with `splitBy` render as stacked bars
`tab`	string	No	Dashboard tab name. Default is `application`. Use the same `tab` value to group charts together
`color`	string	No	Color hint (e.g., `"error"`)
`transform`	object	No	Transform the data (e.g., `{ "type": "percentage", "numerator": ["Error"], "denominator": ["Success", "Error"] }`)
`overlayMetrics`	array	No	Additional metrics to overlay on the same chart (e.g., `[{ "metric": "WorkerCapacity", "label": "Capacity" }]`)
`seriesStyles`	object	No	Per-series styling (e.g., `{ "Capacity": { "borderDash": [6, 3] } }`)
`namespace`	string	No	CloudWatch namespace for infrastructure metrics (e.g., `"AWS/ECS"`)
`fixedDimensions`	object	No	Fixed CloudWatch dimension values for infrastructure metrics
`unit`	string	No	Display unit override (e.g., `"Percent"`)

Stat types

Stat	Description
`Sum`	Total value (default for `Count` unit)
`Average`	Mean value (default for `Milliseconds`, `Seconds`, `Bytes`)
`Minimum`	Lowest value
`Maximum`	Highest value
`SampleCount`	Number of data points
`p50`	50th percentile
`p90`	90th percentile
`p95`	95th percentile
`p99`	99th percentile

Built-in metrics

The framework ships with default metrics that require no configuration:

Metric	Unit	Description
`RequestCount`	Count	HTTP requests, service calls, and page views
`Latency`	Milliseconds	Request and service call duration
`WorkflowJobCount`	Count	Workflow job events (started, completed, failed)
`WorkflowJobDuration`	Milliseconds	Workflow job execution time
`WorkflowStepCount`	Count	Workflow step events
`WorkerDemand`	Count	Current worker demand
`WorkerCapacity`	Count	Total worker capacity

Default charts are included for request count by status, error rate, latency percentiles, workflow job status, and infrastructure metrics (CPU, memory, task count).

Default metrics.json

Every scaffolded app includes the following metrics.json:

{
  "metrics": [
    {
      "name": "RequestCount",
      "unit": "Count",
      "value": 1,
      "dimensions": ["type", "statusCategory"],
      "filter": { "type": ["http_request", "service_call", "page_view"] }
    },
    {
      "name": "Latency",
      "unit": "Milliseconds",
      "value": "ms",
      "dimensions": ["type"],
      "filter": { "type": ["http_request", "service_call"] }
    },
    {
      "name": "WorkerDemand",
      "unit": "Count",
      "value": "demand",
      "dimensions": [],
      "filter": { "type": ["worker_scaling"] }
    },
    {
      "name": "WorkerCapacity",
      "unit": "Count",
      "value": "totalCapacity",
      "dimensions": [],
      "filter": { "type": ["worker_scaling"] }
    },
    {
      "name": "WorkflowJobCount",
      "unit": "Count",
      "value": 1,
      "dimensions": ["workflowEvent", "statusCategory"],
      "filter": { "type": ["workflow_job"] }
    },
    {
      "name": "WorkflowJobDuration",
      "unit": "Milliseconds",
      "value": "ms",
      "dimensions": ["workflowEvent"],
      "filter": { "type": ["workflow_job"] }
    },
    {
      "name": "WorkflowStepCount",
      "unit": "Count",
      "value": 1,
      "dimensions": ["workflowEvent", "statusCategory"],
      "filter": { "type": ["workflow_step"] }
    }
  ],
  "dimensions": {
    "type": {
      "field": "type",
      "buckets": {
        "HTTP Request": "http_request",
        "Service Call": "service_call",
        "Page View": "page_view",
        "Workflow Job": "workflow_job",
        "Workflow Step": "workflow_step"
      }
    },
    "statusCategory": {
      "field": "status",
      "buckets": {
        "Success": [200, 399],
        "Warning": [400, 499],
        "Error": [500, 599]
      }
    },
    "workflowEvent": {
      "field": "event",
      "buckets": {
        "Started": "started",
        "Completed": "completed",
        "Failed": "failed",
        "Retry": "retry"
      }
    }
  },
  "charts": [
    {
      "title": "Request Count by Status",
      "metric": "RequestCount",
      "stat": "Sum",
      "chartType": "bar",
      "splitBy": "statusCategory"
    },
    {
      "title": "Request Count by Type",
      "metric": "RequestCount",
      "stat": "Sum",
      "chartType": "line",
      "splitBy": "type"
    },
    {
      "title": "Error Rate",
      "metric": "RequestCount",
      "stat": "Sum",
      "chartType": "line",
      "splitBy": "statusCategory",
      "color": "error",
      "transform": {
        "type": "percentage",
        "numerator": ["Error"],
        "denominator": ["Success", "Warning", "Error"]
      }
    },
    {
      "title": "Average Latency by Type",
      "metric": "Latency",
      "stat": "Average",
      "chartType": "line",
      "splitBy": "type"
    },
    {
      "title": "P95 Latency by Type",
      "metric": "Latency",
      "stat": "p95",
      "chartType": "line",
      "splitBy": "type"
    },
    {
      "title": "Max Latency by Type",
      "metric": "Latency",
      "stat": "Maximum",
      "chartType": "line",
      "splitBy": "type"
    },
    {
      "title": "App CPU Utilization",
      "metric": "CPUUtilization",
      "stat": "Average",
      "chartType": "line",
      "unit": "Percent",
      "tab": "infrastructure",
      "namespace": "AWS/ECS",
      "fixedDimensions": { "ClusterName": "${CLUSTER_NAME}", "ServiceName": "${APP_SERVICE_NAME}" }
    },
    {
      "title": "App Memory Utilization",
      "metric": "MemoryUtilization",
      "stat": "Average",
      "chartType": "line",
      "unit": "Percent",
      "tab": "infrastructure",
      "namespace": "AWS/ECS",
      "fixedDimensions": { "ClusterName": "${CLUSTER_NAME}", "ServiceName": "${APP_SERVICE_NAME}" }
    },
    {
      "title": "App Task Count",
      "metric": "RunningTaskCount",
      "stat": "Average",
      "chartType": "line",
      "unit": "Count",
      "tab": "infrastructure",
      "namespace": "ECS/ContainerInsights",
      "fixedDimensions": { "ClusterName": "${CLUSTER_NAME}", "ServiceName": "${APP_SERVICE_NAME}" },
      "overlayMetrics": [{ "metric": "DesiredTaskCount", "label": "Desired" }],
      "seriesStyles": { "Desired": { "borderDash": [6, 3] } }
    },
    {
      "title": "Worker CPU Utilization",
      "metric": "CPUUtilization",
      "stat": "Average",
      "chartType": "line",
      "unit": "Percent",
      "tab": "infrastructure",
      "namespace": "AWS/ECS",
      "fixedDimensions": { "ClusterName": "${CLUSTER_NAME}", "ServiceName": "${WORKER_SERVICE_NAME}" }
    },
    {
      "title": "Worker Memory Utilization",
      "metric": "MemoryUtilization",
      "stat": "Average",
      "chartType": "line",
      "unit": "Percent",
      "tab": "infrastructure",
      "namespace": "AWS/ECS",
      "fixedDimensions": { "ClusterName": "${CLUSTER_NAME}", "ServiceName": "${WORKER_SERVICE_NAME}" }
    },
    {
      "title": "Worker Task Count",
      "metric": "RunningTaskCount",
      "stat": "Average",
      "chartType": "line",
      "unit": "Count",
      "tab": "infrastructure",
      "namespace": "ECS/ContainerInsights",
      "fixedDimensions": { "ClusterName": "${CLUSTER_NAME}", "ServiceName": "${WORKER_SERVICE_NAME}" },
      "overlayMetrics": [{ "metric": "DesiredTaskCount", "label": "Desired" }],
      "seriesStyles": { "Desired": { "borderDash": [6, 3] } }
    },
    {
      "title": "Worker Demand vs Capacity",
      "metric": "WorkerDemand",
      "stat": "Maximum",
      "chartType": "line",
      "unit": "Count",
      "tab": "infrastructure",
      "overlayMetrics": [{ "metric": "WorkerCapacity", "label": "Capacity" }],
      "seriesStyles": { "Capacity": { "borderDash": [6, 3] } }
    },
    {
      "title": "Workflow Jobs by Status",
      "metric": "WorkflowJobCount",
      "stat": "Sum",
      "chartType": "bar",
      "splitBy": "statusCategory",
      "tab": "workflows"
    },
    {
      "title": "Workflow Jobs by Event",
      "metric": "WorkflowJobCount",
      "stat": "Sum",
      "chartType": "line",
      "splitBy": "workflowEvent",
      "tab": "workflows"
    },
    {
      "title": "Workflow Job Failure Rate",
      "metric": "WorkflowJobCount",
      "stat": "Sum",
      "chartType": "line",
      "splitBy": "statusCategory",
      "color": "error",
      "tab": "workflows",
      "transform": {
        "type": "percentage",
        "numerator": ["Error"],
        "denominator": ["Success", "Error"]
      }
    },
    {
      "title": "Workflow Job Duration (P95)",
      "metric": "WorkflowJobDuration",
      "stat": "p95",
      "chartType": "line",
      "splitBy": "workflowEvent",
      "tab": "workflows"
    },
    {
      "title": "Workflow Steps by Status",
      "metric": "WorkflowStepCount",
      "stat": "Sum",
      "chartType": "bar",
      "splitBy": "statusCategory",
      "tab": "workflows"
    },
    {
      "title": "Workflow Steps by Event",
      "metric": "WorkflowStepCount",
      "stat": "Sum",
      "chartType": "line",
      "splitBy": "workflowEvent",
      "tab": "workflows"
    }
  ]
}

Monitoring

The dashboard at /admin/monitoring/dashboard displays all configured charts organized by tab. Logs are searchable at /admin/monitoring/logs with filtering by source, type, user, and trace ID. For more information on viewing metrics and logs for deployed apps, see the Monitoring documentation. Metrics and logs are also available through the observability API for external monitoring integrations.

Platform Docs

Synthetiq Desktop

Synthetiq CLI

App Framework

Services Framework

Workflows Framework

Platform API

Deployments

Metrics reference

Structured logging

Client-side logging

metrics.json schema

Metrics

Dimensions

Charts

Stat types

Built-in metrics

Default metrics.json

Monitoring

​Structured logging

​Client-side logging

​metrics.json schema

​Metrics

​Dimensions

​Charts

​Stat types

​Built-in metrics

​Default metrics.json

​Monitoring

Structured logging

Client-side logging

metrics.json schema

Metrics

Dimensions

Charts

Stat types

Built-in metrics

Default metrics.json

Monitoring