diff --git a/examples/process-instrumentation/process-instrumentation-grafana-dashboard-sample.json b/examples/process-instrumentation/process-instrumentation-grafana-dashboard-sample.json new file mode 100644 index 0000000000..3d8dceff0c --- /dev/null +++ b/examples/process-instrumentation/process-instrumentation-grafana-dashboard-sample.json @@ -0,0 +1,640 @@ +{ + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": { + "type": "grafana", + "uid": "-- Grafana --" + }, + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "target": { + "limit": 100, + "matchAny": false, + "tags": [], + "type": "dashboard" + }, + "type": "dashboard" + } + ] + }, + "editable": true, + "fiscalYearStartMonth": 0, + "graphTooltip": 0, + "id": 2, + "links": [], + "liveNow": false, + "panels": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "description": "The amount of committed virtual memory. One way to think of this is all the address space this process can read from without triggering an access violation; this includes memory backed solely by RAM, by a swapfile/pagefile and by other mapped files on disk.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [ + { + "__systemRef": "hideSeriesFrom", + "matcher": { + "id": "byNames", + "options": { + "mode": "exclude", + "names": [ + "{__name__=\"process_memory_virtual_By\", instance=\"localhost:9464\", job=\"otel\"}" + ], + "prefix": "All except:", + "readOnly": true + } + }, + "properties": [ + { + "id": "custom.hideFrom", + "value": { + "legend": false, + "tooltip": false, + "viz": true + } + } + ] + } + ] + }, + "gridPos": { + "h": 5, + "w": 9, + "x": 0, + "y": 0 + }, + "id": 4, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "process_memory_virtual_By", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "virtual memory usage", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "description": "the amount of physical memory allocated", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 10, + "x": 9, + "y": 0 + }, + "id": 2, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "process_memory_usage_By", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "physical memory usage", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "description": "Total CPU seconds broken down by states.\nProcess.UserProcessorTime: Gets the user processor time.\nProcess.PrivilegedProcessorTime: Gets the privileged processor time.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 6, + "w": 9, + "x": 0, + "y": 5 + }, + "id": 6, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "process_cpu_time_s", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "cpu time", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "description": "Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [ + { + "__systemRef": "hideSeriesFrom", + "matcher": { + "id": "byNames", + "options": { + "mode": "exclude", + "names": [ + "{instance=\"localhost:9464\", job=\"otel\"}" + ], + "prefix": "All except:", + "readOnly": true + } + }, + "properties": [ + { + "id": "custom.hideFrom", + "value": { + "legend": false, + "tooltip": false, + "viz": true + } + } + ] + } + ] + }, + "gridPos": { + "h": 6, + "w": 10, + "x": 9, + "y": 5 + }, + "id": 12, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "100 * (delta(process_cpu_time_s{state='system'}[30s])/ignoring(state)(process_cpu_count__processors_* 30))", + "legendFormat": "__auto", + "range": true, + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "100 * (delta(process_cpu_time_s{state='user'}[30s])/ignoring(state)(process_cpu_count__processors_* 30))", + "hide": false, + "legendFormat": "__auto", + "range": true, + "refId": "B" + } + ], + "title": "cpu utilization", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "description": "Process threads count.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisCenteredZero": false, + "axisColorMode": "text", + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 9, + "x": 0, + "y": 11 + }, + "id": 10, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "process_threads__threads_", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "thread count", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "description": "The number of processors (CPU cores) available.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 5, + "w": 3, + "x": 9, + "y": 11 + }, + "id": 8, + "options": { + "orientation": "auto", + "reduceOptions": { + "calcs": [ + "lastNotNull" + ], + "fields": "", + "values": false + }, + "showThresholdLabels": false, + "showThresholdMarkers": true + }, + "pluginVersion": "9.3.6", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "InQLY014z" + }, + "editorMode": "code", + "expr": "process_cpu_count__processors_", + "legendFormat": "__auto", + "range": true, + "refId": "A" + } + ], + "title": "cpu count", + "type": "gauge" + } + ], + "refresh": "5s", + "schemaVersion": 37, + "style": "dark", + "tags": [], + "templating": { + "list": [] + }, + "time": { + "from": "now-2h", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "process instrumentation", + "uid": "WPv6P0JVk", + "version": 6, + "weekStart": "" +} diff --git a/src/OpenTelemetry.Instrumentation.Process/README.md b/src/OpenTelemetry.Instrumentation.Process/README.md index 89c3c949b6..83686c293b 100644 --- a/src/OpenTelemetry.Instrumentation.Process/README.md +++ b/src/OpenTelemetry.Instrumentation.Process/README.md @@ -5,13 +5,12 @@ This is an [Instrumentation Library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library), -which instruments [.NET](https://docs.microsoft.com/dotnet) and -collect telemetry about process behavior. +which instruments [.NET](https://docs.microsoft.com/dotnet) and collects +telemetry about process behavior. The process metric instruments being implemented are following OpenTelemetry -[metrics semantic conventions][1]. - -[1]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/process-metrics.md#metric-instruments +[metrics semantic +conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/process-metrics.md#metric-instruments). ## Steps to enable OpenTelemetry.Instrumentation.Process @@ -46,7 +45,23 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder() ``` Refer to [Program.cs](../../examples/process-instrumentation/Program.cs) for a -complete demo. +complete demo. This examples sets up the OpenTelemetry Prometheus exporter, +which requires adding the package +[`OpenTelemetry.Exporter.Prometheus.HttpListener`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.Prometheus.HttpListener/README.md) +to the application. + +Additionally, this +[document](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/metrics/getting-started-prometheus-grafana/README.md) +shows how to use Prometheus and Grafana to build a dashboard for your +application. +[This](../../examples/process-instrumentation/process-instrumentation-grafana-dashboard-sample.json) +is the Grafana dashboard template which has all the metrics currently supported +by this package; plus an additional aggregated metric `CPU utilization` +calculated with the raw metrics, `CPU time` and `CPU count`. + +Please follow the instructions in this +[document](https://grafana.com/docs/grafana/v9.0/dashboards/export-import/) to +import a Grafana dashboard by uploading the JSON template file. ## Metrics @@ -61,15 +76,15 @@ The amount of physical memory allocated for this process. The API used to retrieve the value is: * [Process.WorkingSet64](https://learn.microsoft.com/dotnet/api/system.diagnostics.process.workingset64): -Gets the amount of physical memory, in bytes, -allocated for the associated process. +Gets the amount of physical memory, in bytes, allocated for the associated +process. ### process.memory.virtual -The amount of committed virtual memory for this process. -One way to think of this is all the address space this process can read from -without triggering an access violation; this includes memory backed solely by RAM, -by a swapfile/pagefile and by other mapped files on disk. +The amount of committed virtual memory for this process. One way to think of +this is all the address space this process can read from without triggering an +access violation; this includes memory backed solely by RAM, by a +swapfile/pagefile and by other mapped files on disk. | Units | Instrument Type | Value Type | |-------|-------------------------|------------| @@ -78,8 +93,8 @@ by a swapfile/pagefile and by other mapped files on disk. The API used to retrieve the value is: * [Process.VirtualMemorySize64](https://learn.microsoft.com/dotnet/api/system.diagnostics.process.virtualmemorysize64): -Gets the amount of the virtual memory, in bytes, -allocated for the associated process. +Gets the amount of the virtual memory, in bytes, allocated for the associated +process. ### process.cpu.time @@ -105,14 +120,14 @@ The number of processors (CPU cores) available to the current process. |---------------|-------------------------|------------| | `{processors}`| ObservableUpDownCounter | `Int32` | -The API used to retrieve the value is [System.Environment.ProcessorCount](https://learn.microsoft.com/dotnet/api/system.environment.processorcount). - -> **Note** -> This metric is under [discussion][2] and not part of the -[Process Metrics Spec][3] at this time. +The API used to retrieve the value is +[System.Environment.ProcessorCount](https://learn.microsoft.com/dotnet/api/system.environment.processorcount). -[2]: https://github.com/open-telemetry/opentelemetry-specification/issues/3200 -[3]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/process-metrics.md +> **Note** This metric is under +> [discussion](https://github.com/open-telemetry/opentelemetry-specification/issues/3200) +and not part of the [Process Metrics +Spec](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/process-metrics.md) +at this time. ### process.threads @@ -125,8 +140,7 @@ Process threads count. The API used to retrieve the value is: * [Process.Threads](https://learn.microsoft.com/dotnet/api/system.diagnostics.process.threads): -Gets the set of threads that are running -in the associated process. +Gets the set of threads that are running in the associated process. ## References