dotnetdiag

README

.NET diagnostics

The package provides means for .Net runtime diagnostics implemented in Golang:

• Diagnostics IPC Protocol client.
• NetTrace decoder.

Diagnostic IPC Client

# go get github.com/pyroscope-io/dotnetdiag

Supported .NET versions:

• .NET 5.0
• .NET Core 3.1

Supported platforms:

• Windows
• Linux
• MacOS

Implemented commands:

• StopTracing
• CollectTracing
• CollectTracing2
• CreateCoreDump
• AttachProfiler
• ProcessInfo
• ResumeRuntime

NetTrace decoder

# go get github.com/pyroscope-io/dotnetdiag/nettrace

Supported format versions: <= 4

The decoder deserializes NetTrace binary stream to the object sequence. The package contains an example stream handler implementation that processes events from Microsoft-DotNETCore-SampleProfiler provider. See examples directory.

Documentation

Index

• Constants
• Variables
• func DefaultServerAddress(pid int) string
• type Client
  • func NewClient(addr string, options ...Option) *Client
  • func (c *Client) CollectTracing(config CollectTracingConfig) (s *Session, err error)
  • func (c *Client) StopTracing(sessionID uint64) error
• type CollectTracingConfig
• type CollectTracingPayload
  • func (p CollectTracingPayload) Bytes() []byte
• type CollectTracingResponse
• type Dialer
  • func DefaultDialer() Dialer
• type ErrorResponse
• type Format
• type Header
• type Option
  • func WithDialer(d Dialer) Option
• type ProviderConfig
• type Session
  • func (s *Session) Close() error
  • func (s *Session) Read(b []byte) (int, error)
• type StopTracingPayload
  • func (p StopTracingPayload) Bytes() []byte
• type StopTracingResponse

Constants

const (
	CommandSetDump
	CommandSetEventPipe
	CommandSetProfiler
	CommandSetProcess

	CommandSetServer = 0xFF
)

const (
	EventPipeStopTracing
	EventPipeCollectTracing
	EventPipeCollectTracing2
)

Variables

var (
	ErrSessionIDMismatch = fmt.Errorf("session ID missmatch")
	ErrHeaderMalformed   = fmt.Errorf("malformed header")
	ErrDiagnosticServer  = fmt.Errorf("diagnostic server")
)

Functions

func DefaultServerAddress

func DefaultServerAddress(pid int) string

DefaultServerAddress returns Diagnostic Server unix domain socket path for the process given. https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md#transport

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implement Diagnostic IPC Protocol client. https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md

func NewClient

func NewClient(addr string, options ...Option) *Client

NewClient creates a new Diagnostic IPC Protocol client for the transport specified - on Unix/Linux based platforms, a Unix Domain Socket will be used, and on Windows, a Named Pipe will be used:

• /tmp/dotnet-diagnostic-{%d:PID}-{%llu:disambiguation key}-socket (Linux/MacOS)
• \\.\pipe\dotnet-diagnostic-{%d:PID} (Windows)

Refer to documentation for details: https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md#transport

func (*Client) CollectTracing

func (c *Client) CollectTracing(config CollectTracingConfig) (s *Session, err error)

CollectTracing creates a new EventPipe session stream of NetTrace data.

func (*Client) StopTracing

func (c *Client) StopTracing(sessionID uint64) error

StopTracing stops the given streaming session started with CollectTracing.

type CollectTracingConfig

type CollectTracingConfig struct {
	// CircularBufferSizeMB specifies the size of the circular buffer used for
	// buffering event data while streaming
	CircularBufferSizeMB uint32
	// Providers member lists providers to turn on for a streaming session.
	// See ETW documentation for a more detailed explanation of Keywords, Filters, and Log Level:
	// https://docs.microsoft.com/en-us/message-analyzer/system-etw-provider-event-keyword-level-settings
	Providers []ProviderConfig
}

CollectTracingConfig contains supported parameters for CollectTracing command.

type CollectTracingPayload

type CollectTracingPayload struct {
	CircularBufferSizeMB uint32
	Format               Format
	Providers            []ProviderConfig
}

func (CollectTracingPayload) Bytes

func (p CollectTracingPayload) Bytes() []byte

type CollectTracingResponse

type CollectTracingResponse struct {
	SessionID uint64
}

type Dialer

type Dialer func(addr string) (net.Conn, error)

Dialer establishes connection to the given address. Due to the potential for an optional continuation in the Diagnostics IPC Protocol, each successful connection between the runtime and a Diagnostic Port is only usable once.

Note that the dialer is OS-specific, refer to documentation for details: https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md#transport

func DefaultDialer

func DefaultDialer() Dialer

type ErrorResponse

type ErrorResponse struct {
	Code uint32
}

type Format

type Format uint32

const (
	FormatNetPerf Format = iota
	FormatNetTrace
)

type Header

type Header struct {
	Magic      [14]uint8
	Size       uint16
	CommandSet uint8
	CommandID  uint8
	Reserved   uint16
}

type Option

type Option func(*Client)

Option overrides default Client parameters.

func WithDialer

func WithDialer(d Dialer) Option

WithDialer overrides default dialer function with d.

type ProviderConfig

type ProviderConfig struct {
	Keywords     uint64
	LogLevel     uint32
	ProviderName string
	FilterData   string
}

type Session

type Session struct {
	ID uint64
	// contains filtered or unexported fields
}

Session represents EventPipe stream of NetTrace data created with `CollectTracing` command.

A session is expected to be closed with `StopTracing` call (or `Close`), as there is a "run down" at the end of a stream session that transmits additional metadata. If the stream is stopped prematurely due to a client or server error, the NetTrace stream will be incomplete and should be considered corrupted.

func (*Session) Close

func (s *Session) Close() error

func (*Session) Read

func (s *Session) Read(b []byte) (int, error)

type StopTracingPayload

type StopTracingPayload struct {
	SessionID uint64
}

func (StopTracingPayload) Bytes

func (p StopTracingPayload) Bytes() []byte

type StopTracingResponse

type StopTracingResponse struct {
	SessionID uint64
}