Package tag

Variables

var (
    // TTLUnlimitedPropagation is TTL metadata that allows tag to propagate without any limits on number of hops.
    TTLUnlimitedPropagation = TTL{/* contains filtered or unexported fields */}

    // TTLNoPropagation is TTL metadata that prevents tag from propagating.
    TTLNoPropagation = TTL{/* contains filtered or unexported fields */}
)

func DecodeEach ¶

func DecodeEach(bytes []byte, fn func(key Key, val string, md metadatas)) error

DecodeEach decodes the given serialized tag map, calling handler for each tag key and value decoded.

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.

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.

osKey := tag.MustNewKey("example.com/keys/user-os")
userIDKey := tag.MustNewKey("example.com/keys/user-id")

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

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.

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

_ = ctx // use context

type Key ¶

Key represents a tag key.

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

func MustNewKey ¶

func MustNewKey(name string) Key

MustNewKey returns a key with the given name, and panics if name is an invalid key name.

key := tag.MustNewKey("example.com/keys/user-os")
_ = key // use key

func NewKey ¶

func NewKey(name string) (Key, error)

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

// Get a key to represent user OS.
key, err := tag.NewKey("example.com/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 ¶

Map is a map of tags. Use New to create a context containing a new Map.

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

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.

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 Metadata ¶

Metadata applies metadatas specified by the function.

type Metadata func(*metadatas)

func WithTTL ¶

func WithTTL(ttl TTL) Metadata

WithTTL applies metadata with provided ttl.

type Mutator ¶

Mutator modifies a tag map.

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

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, mds ...Metadata) 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. Metadata applies metadata to the tag. It is optional. Metadatas are applied in the order in which it is provided. If more than one metadata updates the same attribute then the update from the last metadata prevails.

func Update ¶

func Update(k Key, v string, mds ...Metadata) 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. Metadata applies metadata to the tag. It is optional. Metadatas are applied in the order in which it is provided. If more than one metadata updates the same attribute then the update from the last metadata prevails.

func Upsert ¶

func Upsert(k Key, v string, mds ...Metadata) 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. Metadata applies metadata to the tag. It is optional. Metadatas are applied in the order in which it is provided. If more than one metadata updates the same attribute then the update from the last metadata prevails.

type TTL ¶

TTL is metadata that specifies number of hops a tag can propagate. Details about TTL metadata is specified at https://github.com/census-instrumentation/opencensus-specs/blob/master/tags/TagMap.md#tagmetadata

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

type Tag ¶

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

type Tag struct {
    Key   Key
    Value string
}