package tag

import "go.opencensus.io/tag"

Package tag contains OpenCensus tags.

Tags are key-value pairs. Tags provide additional cardinality to the OpenCensus instrumentation data.

Tags can be propagated on the wire and in the same process via context.Context. Encode and Decode should be used to represent tags into their binary propagation form.

Index ¶

• func Do(ctx context.Context, f func(ctx context.Context))
• func Encode(m *Map) []byte
• func New(ctx context.Context, mutator ...Mutator) (context.Context, error)
• func NewContext(ctx context.Context, m *Map) context.Context
• type Key
• func NewKey(name string) (Key, error)
• func (k Key) Name() string
• type Map
• func Decode(bytes []byte) (*Map, error)
• func FromContext(ctx context.Context) *Map
• func (m *Map) String() string
• func (m *Map) Value(k Key) (string, bool)
• type Mutator
• func Delete(k Key) Mutator
• func Insert(k Key, v string) Mutator
• func Update(k Key, v string) Mutator
• func Upsert(k Key, v string) Mutator
• type Tag

Examples ¶

• Do
• FromContext
• New
• New (Replace)
• NewContext
• NewKey

Functions ¶

func Do ¶

func Do(ctx context.Context, f func(ctx context.Context))

Do is similar to pprof.Do: a convenience for installing the tags from the context as Go profiler labels. This allows you to correlated runtime profiling with stats.

It converts the key/values from the given map to Go profiler labels and calls pprof.Do.

Do is going to do nothing if your Go version is below 1.9.

package main

import (
	"context"
	"log"

	"go.opencensus.io/tag"
)

var (
	ctx context.Context
	key tag.Key
)

func main() {
	ctx, err := tag.New(ctx,
		tag.Insert(key, "macOS-10.12.5"),
		tag.Upsert(key, "macOS-10.12.7"),
	)
	if err != nil {
		log.Fatal(err)
	}
	tag.Do(ctx, func(ctx context.Context) {
		_ = ctx // use context
	})
}

func Encode ¶

func Encode(m *Map) []byte

Encode encodes the tag map into a []byte. It is useful to propagate the tag maps on wire in binary format.

func New ¶

func New(ctx context.Context, mutator ...Mutator) (context.Context, error)

New returns a new context that contains a tag map originated from the incoming context and modified with the provided mutators.

package main

import (
	"context"
	"log"

	"go.opencensus.io/tag"
)

var ctx context.Context

func main() {
	osKey, err := tag.NewKey("my.org/keys/user-os")
	if err != nil {
		log.Fatal(err)
	}
	userIDKey, err := tag.NewKey("my.org/keys/user-id")
	if err != nil {
		log.Fatal(err)
	}

	ctx, err := tag.New(ctx,
		tag.Insert(osKey, "macOS-10.12.5"),
		tag.Upsert(userIDKey, "cde36753ed"),
	)
	if err != nil {
		log.Fatal(err)
	}

	_ = ctx // use context
}

package main

import (
	"context"
	"log"

	"go.opencensus.io/tag"
)

var (
	ctx context.Context
	key tag.Key
)

func main() {
	ctx, err := tag.New(ctx,
		tag.Insert(key, "macOS-10.12.5"),
		tag.Upsert(key, "macOS-10.12.7"),
	)
	if err != nil {
		log.Fatal(err)
	}

	_ = ctx // use context
}

func NewContext ¶

func NewContext(ctx context.Context, m *Map) context.Context

NewContext creates a new context with the given tag map. To propagate a tag map to downstream methods and downstream RPCs, add a tag map to the current context. NewContext will return a copy of the current context, and put the tag map into the returned one. If there is already a tag map in the current context, it will be replaced with m.

package main

import (
	"context"

	"go.opencensus.io/tag"
)

var tagMap *tag.Map

func main() {
	// Propagate the tag map in the current context.
	ctx := tag.NewContext(context.Background(), tagMap)

	_ = ctx // use context
}

Types ¶

type Key ¶

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

Key represents a tag key.

func NewKey ¶

func NewKey(name string) (Key, error)

NewKey creates or retrieves a string key identified by name. Calling NewKey consequently with the same name returns the same key.

package main

import (
	"log"

	"go.opencensus.io/tag"
)

func main() {
	// Get a key to represent user OS.
	key, err := tag.NewKey("my.org/keys/user-os")
	if err != nil {
		log.Fatal(err)
	}
	_ = key // use key
}

func (Key) Name ¶

func (k Key) Name() string

Name returns the name of the key.

type Map ¶

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

Map is a map of tags. Use NewMap to build tag maps.

func Decode ¶

func Decode(bytes []byte) (*Map, error)

Decode decodes the given []byte into a tag map.

func FromContext ¶

func FromContext(ctx context.Context) *Map

FromContext returns the tag map stored in the context.

package main

import (
	"context"

	"go.opencensus.io/tag"
)

var ctx context.Context

func main() {
	tagMap := tag.FromContext(ctx)

	_ = tagMap // use the tag map
}

func (*Map) String ¶

func (m *Map) String() string

func (*Map) Value ¶

func (m *Map) Value(k Key) (string, bool)

Value returns the value for the key if a value for the key exists.

type Mutator ¶

type Mutator interface {
	Mutate(t *Map) (*Map, error)
}

Mutator modifies a tag map.

func Delete ¶

func Delete(k Key) Mutator

Delete returns a mutator that deletes the value associated with k.

func Insert ¶

func Insert(k Key, v string) Mutator

Insert returns a mutator that inserts a value associated with k. If k already exists in the tag map, mutator doesn't update the value.

func Update ¶

func Update(k Key, v string) Mutator

Update returns a mutator that updates the value of the tag associated with k with v. If k doesn't exists in the tag map, the mutator doesn't insert the value.

func Upsert ¶

func Upsert(k Key, v string) Mutator

Upsert returns a mutator that upserts the value of the tag associated with k with v. It inserts the value if k doesn't exist already. It mutates the value if k already exists.

type Tag ¶

type Tag struct {
	Key   Key
	Value string
}

Tag is a key value pair that can be propagated on wire.

Source Files ¶

context.go doc.go key.go map.go map_codec.go profile_19.go validate.go