# Metriken

> Custom Metrics der DataBridge — vorab aggregiert und ohne Sampling.

---

Site [llms.txt](/llms.txt)

---

Neben Traces und Requests sendet die dsyr.DataBridge eigene **Custom Metrics** an
Application Insights. Metriken sind numerische Zeitreihen mit Dimensionen — sie eignen
sich für Dashboards, Trend-Analysen und Metric Alerts, ohne dass dafür Log-Einträge
durchsucht werden müssen.

Die Metriken werden über `TelemetryClient.GetMetric()` **vorab aggregiert**: Das SDK
sammelt die Werte lokal in 1-Minuten-Intervallen und sendet pro Intervall und
Dimensionskombination einen aggregierten Datenpunkt (Summe, Anzahl, Min, Max).

> **Metriken unterliegen keinem Sampling**
>
> Weder das gepufferte Logging noch das Dependency-Sampling noch das
> Application-Insights-Sampling wirken auf Custom Metrics. Für belastbare **Mengenangaben**
> sind sie deshalb die einzige verlässliche Quelle.



## Verfügbare Metriken

Alle Metriken verwenden den Namespace **`DataBridge`**.

| Metrik | Dimensionen | Quelle | Bedeutung |
|---|---|---|---|
| `ChangesDetected` | `JobName` | `GetChanges` → `ProcessJobsForRetrievalInOrderService` | Anzahl der erkannten geänderten Datensätze pro Job und Lauf (kumuliert pro Lauf, inkl. `0`) |
| `MessagesProcessed` | `JobName`, `Outcome` (`Success`/`Failed`/`Transitive`) | `ProcessStandardQueueItems`/`ProcessLowPriorityQueueItems`/`ProcessHighPriorityQueueItems` → `ProcessQueueMessageService` | Eine verarbeitete Queue-Nachricht mit ihrem Ausgang. Queue-übergreifend: alle drei Prioritäts-Queues schreiben in dieselbe Metrik, unterscheidbar nur über den Ausgang, nicht über die Queue. `Transitive` heißt: die Nachricht wurde nicht endgültig verworfen, sondern in eine Retry-Queue umgeleitet. |
| `ProcessingDurationMs` | `JobName` | `ProcessStandardQueueItems`/`ProcessLowPriorityQueueItems`/`ProcessHighPriorityQueueItems` → `ProcessQueueMessageService` | Verarbeitungsdauer einer einzelnen Queue-Nachricht in Millisekunden, unabhängig vom Ausgang. |

> **GetChanges hat keine job-genaue Erfolgs- oder Laufzeit-Metrik**
>
> Für `GetChanges` selbst gibt es aktuell **nur** `ChangesDetected` (Anzahl, kein
> Erfolg/Fehler-Signal) auf Job-Ebene. Erfolgsquote und Laufzeit von `GetChanges` stammen
> aus den automatisch von der Functions-Runtime erzeugten Host-Metriken
> (`GetChanges Successes`/`Failures`/`AvgDurationMs`/…, siehe unten) — die kennen nur den
> gesamten Timer-Lauf, nicht die einzelnen Jobs darin.



> **Null-Werte sind bedeutungstragend**
>
> Auch Läufe ohne erkannte Änderungen schreiben den Wert `0`. Dadurch ist unterscheidbar,
> ob ein Job *gelaufen ist und nichts gefunden hat* oder *gar nicht gelaufen ist* — eine
> **Lücke** in der Serie bedeutet Letzteres. Das macht die Metrik zur besten Grundlage für
> Alerts auf hängende Jobs.



## Anzeige in Azure

### Metrics Explorer

Application Insights → **Metriken** → Namespace `DataBridge` auswählen → Metrik
`ChangesDetected`. Als Aggregation eignet sich **Summe** (Anzahl Datensätze) oder
**Anzahl** (Anzahl Läufe).

> **Einmalige Freischaltung für Dimensionen**
>
> Um im Metrics Explorer nach der Dimension `JobName` zu **filtern oder zu splitten**, muss
> einmalig pro Application-Insights-Ressource die Option **„Enable alerting on custom metric
> dimensions"** aktiviert werden:
> Application Insights → *Usage and estimated costs* → *Custom metrics*.
> 
> Ohne diese Option erscheint die Metrik nur als Gesamtaggregat über alle Jobs.
> Die KQL-Abfrage funktioniert unabhängig davon.



### KQL (Logs)

Jeder aggregierte Datenpunkt landet zusätzlich in der Tabelle `customMetrics`:

```kusto
customMetrics
| where name == "ChangesDetected"
| extend job = tostring(customDimensions["JobName"])
| summarize sum(valueSum) by bin(timestamp, 2m), job
| render timechart
```

## Host-generierte Metriken (Functions-Runtime)

Zusätzlich zu den oben aufgeführten, selbst erzeugten Metriken schreibt die
**Azure-Functions-Runtime automatisch** pro Funktion aggregierte Kennzahlen ebenfalls in
die Tabelle `customMetrics` — ohne dass die DataBridge dafür Code enthält:

```
<FunctionName> Successes
<FunctionName> Failures
<FunctionName> SuccessRate
<FunctionName> AvgDurationMs
<FunctionName> MinDurationMs
<FunctionName> MaxDurationMs
```

`<FunctionName>` ist z. B. `GetChanges`, `ProcessStandardQueueItems`,
`ProcessLowPriorityQueueItems` oder `ProcessHighPriorityQueueItems`. Diese Metriken sind
Standardverhalten des Functions-Hosts (WebJobs SDK Function Result Aggregator) und daher
in **jeder** Azure-Functions-App vorhanden, unabhängig von der DataBridge selbst. Das
[Grafana-Dashboard](../../grafana-dashboard/) nutzt sie für die Kopfzeilen-Tachos und die
`Ausführungen`/`Laufzeiten`-Panels der Zeile „GetChanges".

> **Nur Funktions-Ebene, keine Job-Ebene**
>
> Diese Host-Metriken kennen ausschließlich die aufrufende Funktion, nicht die einzelnen
> Jobs, die innerhalb eines Laufs verarbeitet werden. Für job-genaue Aussagen sind
> `ChangesDetected` bzw. `MessagesProcessed`/`ProcessingDurationMs` maßgeblich.



## Limits

| Limit | Wert | Anmerkung |
|---|---|---|
| Dimensionen pro Metrik | **10** | Azure-Monitor-Limit |
| Zeitreihen pro Metrik (SDK-Default) | 1.000 | `seriesCountLimit` der SDK-Pre-Aggregation |
| Distinct-Werte pro Dimension (SDK-Default) | 100 | `valuesPerDimensionLimit` |

**Konsequenz:** Dimensionswerte müssen **niedrig-kardinal** sein — Job-Namen, Queue-Namen
und Status-Codes sind geeignet; IDs, Zeitstempel oder Datensatz-Schlüssel nicht.