Documentation ¶
Overview ¶
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 ¶
- Variables
- func DecodeEach(bytes []byte, fn func(key Key, val string, md metadatas)) error
- 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
- type Map
- type Metadata
- type Mutator
- type TTL
- type Tag
Examples ¶
Constants ¶
This section is empty.
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 */} )
Functions ¶
func DecodeEach ¶ added in v0.14.0
DecodeEach decodes the given serialized tag map, calling handler for each tag key and value decoded.
func Do ¶ added in v0.2.0
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.
Example ¶
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 }) }
Output:
func Encode ¶
Encode encodes the tag map into a []byte. It is useful to propagate the tag maps on wire in binary format.
func New ¶ added in v0.3.0
New returns a new context that contains a tag map originated from the incoming context and modified with the provided mutators.
Example ¶
package main import ( "context" "log" "go.opencensus.io/tag" ) var ctx context.Context func main() { osKey, err := tag.NewKey("example.com/keys/user-os") if err != nil { log.Fatal(err) } userIDKey, err := tag.NewKey("example.com/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 }
Output:
Example (Replace) ¶
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 }
Output:
func NewContext ¶
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.
Example ¶
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 }
Output:
Types ¶
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key represents a tag key.
func NewKey ¶
NewKey creates or retrieves a string key identified by name. Calling NewKey consequently with the same name returns the same key.
Example ¶
package main import ( "log" "go.opencensus.io/tag" ) func main() { // 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 }
Output:
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is a map of tags. Use New to create a context containing a new Map.
func FromContext ¶
FromContext returns the tag map stored in the context.
Example ¶
package main import ( "context" "go.opencensus.io/tag" ) var ctx context.Context func main() { tagMap := tag.FromContext(ctx) _ = tagMap // use the tag map }
Output:
type Metadata ¶ added in v0.21.0
type Metadata func(*metadatas)
Metadata applies metadatas specified by the function.
type Mutator ¶
Mutator modifies a tag map.
func Insert ¶
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 ¶
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 ¶
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 ¶ added in v0.21.0
type TTL struct {
// contains filtered or unexported fields
}
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