Deprecated: dotnetdiagnostics exporter is deprecated.
README
¶
Dotnet Diagnostics Receiver
| Status | |
|---|---|
| Stability | deprecated |
| Supported pipeline types | metrics |
| Distributions | contrib |
This receiver provides a capability similar to the dotnet-counters tool, which takes a .NET process ID and reads metrics from that process, providing them to the CLI. Similarly, this receiver reads metrics from a given .NET process, translating them and providing them to the Collector.
.NET Counters Overview
The .NET runtime makes available metrics to interested clients over an IPC
connection, listening for requests and responding with metrics sent at a
specified interval. All .NET processes newer than 3.0 make available both
default metrics (grouped under the name System.Runtime) and any custom metrics
generated via the EventCounter
API
.
Once a .NET process is running, a client (such as this receiver) may connect to it over IPC, which is either a Unix domain socket on Linux/macOS, or a named pipe on Windows. After connecting, the client sends the process a request, using a custom binary encoding, indicating both the counters it's interested in and the collection interval, then waits for data. If the request is successful, the .NET process sends metrics, also using a custom binary encoding, over the IPC connection, at the specified interval.
Operation
At startup, this recevier looks for a file in TMPDIR (or /tmp if not set)
corresponding to the given PID and a naming convention. If found, a Unix domain
socket connection is opened, using the file as the endpoint, and a request is
made to the dotnet process for metrics, with the given (in the config)
collection interval and counters.
After that, it listens for metrics arriving from the connection, and sends them to the next consumer as soon as they arrive. If the connection fails, or an unexpected value is read, the receiver shuts down.
Configuration
This receiver accepts three configuration fields: collection_interval,
pid, and counters.
| Field Name | Description | Example | Default |
|---|---|---|---|
collection_interval |
The interval between metric collection (converted to seconds) | 1m |
1s |
pid |
The process ID of the .NET process from which to collect metrics | 1001 |
|
counters |
A list of counter groups (sometimes referred to as providers or event sources) to request from the .NET process | ["MyCounters"] |
["System.Runtime", "Microsoft.AspNetCore.Hosting"] |
Example yaml config:
receivers:
dotnet_diagnostics:
collection_interval: 10s
pid: 23860
counters: [ "MyCounters", "System.Runtime" ]
exporters:
logging:
loglevel: info
service:
pipelines:
metrics:
receivers: [ dotnet_diagnostics ]
exporters: [ logging ]
Usage With Receiver Creator
It is possible to create a config file for this receiver with a hard-coded process id, but it is expected that this receiver will often be used with a receiver creator, and a host observer, to discover .NET processes at runtime.
Example receiver creator config:
extensions:
host_observer:
receivers:
receiver_creator:
watch_observers: [ host_observer ]
receivers:
dotnet_diagnostics:
rule: type.hostport && process_name == 'dotnet'
config:
pid: "`process_id`"
exporters:
logging:
loglevel: info
service:
extensions: [ host_observer ]
pipelines:
metrics:
receivers: [ receiver_creator ]
exporters: [ logging ]
Supported Versions
This receiver is compatible with .NET Core 3.0 and later versions, running on Linux or macOS. Windows is not yet supported.
External Resources
https://github.com/dotnet/diagnostics/blob/master/documentation/design-docs/ipc-protocol.md
https://github.com/Microsoft/perfview/blob/main/src/TraceEvent/EventPipe/EventPipeFormat.md
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewFactory ¶
Types ¶
type Config ¶
type Config struct {
// ScraperController's collection_interval is used to set the interval between
// metric collection. The interval is converted to seconds and sent to the
// dotnet backend at receiver startup time. The dotnet process then sends the
// receiver data at the specified interval. Defaults to 1 second.
scraperhelper.ScraperControllerSettings `mapstructure:",squash"`
// The process ID of the dotnet process from which to collect diagnostics. This
// process ID is used to generate the file glob "dotnet-diagnostic-%d-*-socket"
// to locate a file in TMPDIR (or "/tmp" if unset). If the file is found, it is
// used as a Unix domain socket (on Linux/Mac) to communicate with the dotnet
// process. For ease of use, this receiver is intended to be used with an
// observer and receiver creator for process discovery and receiver creation.
PID int `mapstructure:"pid"`
// A list of counters for the dotnet process to send to the collector. Defaults
// to ["System.Runtime", "Microsoft.AspNetCore.Hosting"]. Available counters can
// be displayed by the `dotnet-counters` tool:
// https://docs.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters
Counters []string `mapstructure:"counters"`
// LocalDebugDir takes an optional directory name where stream data can be written for
// offline analysis and troubleshooting. If LocalDebugDir is empty, no stream data is
// written. If it has a value, MaxLocalDebugFiles also needs to be set, and stream
// data will be written to disk at the specified location using the naming
// convention `msg.%d.bin` as each message is received, where %d is the current
// message number.
LocalDebugDir string `mapstructure:"local_debug_dir"`
// MaxLocalDebugFiles indicates the maximum number of files kept in LocalDebugDir. When a
// file is written, the oldest one will be deleted if necessary to keep the
// number of files in LocalDebugDir at the specified maximum.
MaxLocalDebugFiles int `mapstructure:"max_local_debug_files"`
}
Source Files
Directories