tracefs

Documentation

Overview

Package tracefs instruments a filesystem for distributed tracing operations. The OpenTelemetry API is supported.

This is not strictly a filesystem implementation, but rather a wrapper around an existing filesystem. As such, it does not implement the fsimpl.FSProvider interface.

Usage

To use this filesystem, call New with a base filesystem. All operations on the returned filesystem will be instrumented.

In order to report traces, an OTel trace.TracerProvider must first be set up. The details of this are outside the scope of this module, but see the fscli example in this repository's examples directory for one approach.

A trace.TracerProvider can optionally be passed to New using WithTracerProvider.

Propagation

By default, this filesystem will use the global propagation.TextMapPropagator to extract trace information from the context. This can be overridden by passing a propagation.TextMapPropagator to WithPropagators.

Index

• func BaseURL(url string) attribute.KeyValue
• func DirEntries(n int) attribute.KeyValue
• func FileBytesRead(n int) attribute.KeyValue
• func FileModTime(t time.Time) attribute.KeyValue
• func FilePerms(perms string) attribute.KeyValue
• func FileSize(n int64) attribute.KeyValue
• func New(ctx context.Context, fsys fs.FS, opts ...Option) (fs.FS, error)
• func Path(name string) attribute.KeyValue
• func Pattern(pattern string) attribute.KeyValue
• func Type(name string) attribute.KeyValue
• type Option
  • func WithPropagators(propagators propagation.TextMapPropagator) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option

Functions

func BaseURL

func BaseURL(url string) attribute.KeyValue

The base URL of the file system.

Type: string Required: No Examples: "https://example.com", "file:///tmp"

func DirEntries

func DirEntries(n int) attribute.KeyValue

The number of entries in a directory.

Type: int Required: No Examples: 3, 0

func FileBytesRead

func FileBytesRead(n int) attribute.KeyValue

The number of bytes read from a file during a Read operation.

Type: int Required: No Examples: 1024, 0

func FileModTime

func FileModTime(t time.Time) attribute.KeyValue

The modification time of a file.

Type: time.Time Required: No Examples: "2021-08-21T11:10:00Z", "2021-08-21T11:10:00-07:00"

func FilePerms

func FilePerms(perms string) attribute.KeyValue

The permissions of a file.

Type: string Required: No Examples: "-rw-r--r--", "drwxr-xr-x"

func FileSize

func FileSize(n int64) attribute.KeyValue

The size of a file.

Type: int64 Required: No Examples: 1024, 0

func New

func New(ctx context.Context, fsys fs.FS, opts ...Option) (fs.FS, error)

New returns a filesystem (an fs.FS) that instruments the given filesystem, adding trace spans for each operation. The given context will be used for the root span. Options can be provided to configure the behaviour of the instrumented filesystem.

func Path

func Path(name string) attribute.KeyValue

The path being operated on.

Type: string Required: Yes Examples: "README.md", "example/directory/foo.txt"

func Pattern

func Pattern(pattern string) attribute.KeyValue

The pattern used (by Glob) to match files.

Type: string Required: No Examples: "*.txt", "foo/**"

func Type

func Type(name string) attribute.KeyValue

The type of filesystem being operated on.

Type: string Required: No Examples: "gitfs", "httpfs", "filefs"

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option specifies instrumentation configuration options.

func WithPropagators

func WithPropagators(propagators propagation.TextMapPropagator) Option

WithPropagators specifies propagators to use for extracting information from the HTTP requests. If none are specified, global ones will be used.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used (see otel.GetTracerProvider).