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) *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 ErrorResponse
• type Format
• type Header
• 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

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#CollectStreaming

func NewClient

func NewClient(addr string) *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 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 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
}