From bdb917eb4cb0c380b987a76ce49a95f6a19e58f5 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Tue, 6 Sep 2022 11:11:04 -0700 Subject: [PATCH] Merge main into new_sdk/main (#3141) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Use already enabled revive linter and add depguard (#2883) * Refactor golangci-lint conf Order settings alphabetically. * Add revive settings to golangci conf * Check blank imports * Check bool-literal-in-expr * Check constant-logical-expr * Check context-as-argument * Check context-key-type * Check deep-exit * Check defer * Check dot-imports * Check duplicated-imports * Check early-return * Check empty-block * Check empty-lines * Check error-naming * Check error-return * Check error-strings * Check errorf * Stop ignoring context first arg in tests * Check exported comments * Check flag-parameter * Check identical branches * Check if-return * Check increment-decrement * Check indent-error-flow * Check deny list of go imports * Check import shadowing * Check package comments * Check range * Check range val in closure * Check range val address * Check redefines builtin id * Check string-format * Check struct tag * Check superfluous else * Check time equal * Check var naming * Check var declaration * Check unconditional recursion * Check unexported return * Check unhandled errors * Check unnecessary stmt * Check unnecessary break * Check waitgroup by value * Exclude deep-exit check in example*_test.go files * Move the minimum version to go 1.17 (#2917) * Move the minimum version to go 1.17 * Update readme and changelog Co-authored-by: Chester Cheung * Use ByteSliceToString from golang.org/x/sys/unix (#2924) Use unix.ByteSliceToString to convert Utsname []byte fields to strings. This also allows to drop the charsToString helper which serves the same purpose and matches ByteSliceToString's implementation. Signed-off-by: Tobias Klauser Co-authored-by: Tyler Yahn * docs: fix typo (#2935) * add timeout to grpc connection in otel-collector example (#2939) * Closes: #2951 (#2952) This PR updates the example listed in the getting started doc so that it will compile without error. It also makes this example consistent with the code found in https://github.com/open-telemetry/opentelemetry-go/blob/main/example/fib/main.go Signed-off-by: Brad Topol * fix data-model link (#2955) * Bump go.opentelemetry.io/proto/otlp from v0.16.0 to v0.18.0 (#2960) * Move to using Instrumentation Scope (#2976) * Move to using Instrumentation Scope * Use type alias, not definition * Add a changelog entry * docs(website_docs): fix exporting_data.md and getting-started.md toc (#2930) * docs(website_docs): fix toc * docs(website_docs): fix toc * update exporting_data.md for rerun check-links * update exporting_data.md for rerun check-links Co-authored-by: Chester Cheung Co-authored-by: Tyler Yahn * Update getting-started.md (#2984) grammar edit for line 175 of readme * fix typo (#2986) * fix typo * spell fix * typo fix (#2991) * added traces.txt to gitignore for fib (#2993) * Deprecate Library and move all uses to Scope (#2977) * Deprecate Library and move all uses to Scope * Add PR number to changelog * Don't change signatures in stable modules * Revert some changes * Rename internal struct names * A bit more renaming * Update sdk/trace/span.go Co-authored-by: Tyler Yahn * Update based on feedback * Revert change Co-authored-by: Tyler Yahn Co-authored-by: Anthony Mirabella * Feat/bridge support text map (#2911) * feat: support TextMap * doc: add comment * test: support for ot.TextMap * Retrieve lost code due to merge * fix: retrieve lost code due to merge. test: support for ot.HTTPHeaders * go mod tidy * Optimized code style, add changelog * doc: Restore comments * wip: add test cases * test: fix args error * delete empty line * Fix syntax and changelog errors * Fix formatting errors Co-authored-by: Chester Cheung Co-authored-by: Anthony Mirabella * Add a release template (#2863) * Add a release template * Update the about field Co-authored-by: Damien Mathieu <42@dmathieu.com> * Fix linting Issues * Add ignore for template link Co-authored-by: Damien Mathieu <42@dmathieu.com> Co-authored-by: Chester Cheung Co-authored-by: Anthony Mirabella * Add workflow to automate bundling dependabot PRs (#2997) Signed-off-by: Anthony J Mirabella * Release prep 1.8.0 (#3001) * Update CHANGELOG and versions.yaml for 1.8.0 release Signed-off-by: Anthony J Mirabella * Update go-build-tools Signed-off-by: Anthony J Mirabella * Prepare stable-v1 for version v1.8.0 * Prepare experimental-metrics for version v0.31.0 * Prepare bridge for version v0.31.0 * `make go-mod-tidy` should use `-compat=1.17` now Signed-off-by: Anthony J Mirabella * Update CHANGELOG.md Co-authored-by: Tyler Yahn Co-authored-by: Tyler Yahn * Add benchmark metric test for UpDownCounter (#2655) * add benchmark metric test for UpDownCounter * move counter annotation up * fix syncFloat64 to syncInt64 * fix syncFloat64 to syncInt64 * fix go-lint err * Add semconv/v1.11.0 (#3009) Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Add semconv/v1.12.0 (#3010) * Add semconv/v1.12.0 * Update all semconv use to v1.12.0 Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Add http.method attribute to http server metric (#3018) * Add http.method attribute to http server metric Signed-off-by: Ziqi Zhao * fix lint Signed-off-by: Ziqi Zhao * fix lint Signed-off-by: Ziqi Zhao * fix for reviews Signed-off-by: Ziqi Zhao * add changelog entry Signed-off-by: Ziqi Zhao * Add tests and fix opentracing bridge defer warning (#3029) * add tests and fix opentracing bridge defer warning * add changelog entry * Update CHANGELOG.md Co-authored-by: Tyler Yahn * Update bridge/opentracing/bridge_test.go Co-authored-by: Tyler Yahn Co-authored-by: Tyler Yahn * Introduce "split" metric schema transformation (#2999) This is a new transformation type that allows to describe a change where a metric is converted to several other metrics by eliminating an attribute. An example of such change that happened recently is this: https://github.com/open-telemetry/opentelemetry-specification/pull/2617 This PR implements specification change https://github.com/open-telemetry/opentelemetry-specification/pull/2653 This PR creates package v1.1 for the new functionality. The old package v1.0 remains unchanged. * Release v1.9.0 (#3052) * Bump versions in versions.yaml * Prepare stable-v1 for version v1.9.0 * Prepare experimental-schema for version v0.0.3 * Update changelog for release * Replace ioutil with io and os (#3058) * Make several vars into consts (#3068) * Add support for Go 1.19 (#3077) * Add support for Go 1.19 * Update CHANGELOG.md Co-authored-by: Sam Xie Co-authored-by: Sam Xie * Update compatibility documentation (#3079) Remove 3 month timeline for backwards support of old versions of Go. * Fix `opentracing.Bridge` where it miss identifying the spanKind (#3096) * Fix opentracing.Bridge where it was not identifying the spanKinf correctly * fix test * changelog * Keeping backward comppatibillity * Update CHANGELOG.md Co-authored-by: Anthony Mirabella * Update CHANGELOG.md Co-authored-by: Anthony Mirabella Co-authored-by: Chester Cheung * replace `required` by `requirementlevel` (#3103) * Change the inclusivity of exponential histogram bounds (#2982) * Use lower-inclusive boundaries * make exponent and logarithm more symmetric Co-authored-by: Anthony Mirabella Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Update golangci-lint to v1.48.0 (#3105) * Update golangci-lint to v1.48.0 Co-authored-by: Chester Cheung * Bump go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 (#3107) * Bump go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> * Update tracer to guard for a nil ctx (#3110) * Update tracer to guard for a nil ctx Co-authored-by: Chester Cheung Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> Co-authored-by: Tyler Yahn * Fix sdk/instrumentation pkg docs (#3130) * Add instrumentation scope attributes (#3131) * Add WithScopeAttributes TracerOption to trace API * Add Attributes field to instrumentation Scope * Use scope attributes for new Tracer * Fix stdouttrace expected test output * Allow unexported Set fields in sdk/trace test * Export instrumentation scope attrs in OTLP * Add changes to the changelog * Fix imports with make lint * Add unit tests for WithScopeAttributes * Fix English in Scope documentation * Add WithScopeAttributes MeterOption to metric API package (#3132) * Add WithScopeAttributes MeterOption to metric pkg * Add MeterConfig unit tests * Add changes to changelog * Fix import linting * Update MeterProvider documentation Include information about how to use WithScopeAttributes. * Refactor TracerProvider documentation (#3133) * Refactor TracerProvider documentation * Fix English article * Grammar fixes * consistency-of: Changed signal names for website docs (#3137) * Shut down all processors even on error (#3091) * Fix stdoutmetric example test The merged instrumentation Scope includes SchemaURL and Attributes now, add them to the expected output. Signed-off-by: Brad Topol Signed-off-by: Anthony J Mirabella Signed-off-by: Ziqi Zhao Co-authored-by: Aaron Clawson <3766680+MadVikingGod@users.noreply.github.com> Co-authored-by: Chester Cheung Co-authored-by: Tobias Klauser Co-authored-by: petrie <244236866@qq.com> Co-authored-by: Damien Mathieu <42@dmathieu.com> Co-authored-by: Brad Topol Co-authored-by: Craig Pastro Co-authored-by: Kshitija Murudi Co-authored-by: Petrie Liu Co-authored-by: Guangya Liu Co-authored-by: Craig Pastro Co-authored-by: Anthony Mirabella Co-authored-by: ttoad Co-authored-by: Ziqi Zhao Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Håvard Anda Estensen Co-authored-by: Mikhail Mazurskiy <126021+ash2k@users.noreply.github.com> Co-authored-by: Sam Xie Co-authored-by: Alan Protasio Co-authored-by: Joshua MacDonald Co-authored-by: Mitch Usher Co-authored-by: Gaurang Patel --- CHANGELOG.md | 5 ++ bridge/opentracing/bridge_test.go | 43 ++++++++++++ .../tracetransform/instrumentation.go | 5 +- .../tracetransform/instrumentation_test.go | 52 ++++++++++++++ exporters/stdout/stdoutmetric/example_test.go | 4 +- exporters/stdout/stdouttrace/trace_test.go | 4 +- metric/config.go | 18 +++++ metric/config_test.go | 69 +++++++++++++++++++ metric/meter.go | 51 +++++++++++--- sdk/instrumentation/doc.go | 24 +++++++ sdk/instrumentation/library.go | 7 -- sdk/instrumentation/scope.go | 27 +++++--- sdk/trace/provider.go | 29 +++++--- sdk/trace/provider_test.go | 22 ++++++ sdk/trace/trace_test.go | 12 ++++ sdk/trace/tracer.go | 5 ++ trace/config.go | 18 ++++- trace/config_test.go | 19 +++++ trace/trace.go | 49 ++++++++++--- website_docs/_index.md | 2 +- 20 files changed, 416 insertions(+), 49 deletions(-) create mode 100644 exporters/otlp/otlptrace/internal/tracetransform/instrumentation_test.go create mode 100644 metric/config_test.go create mode 100644 sdk/instrumentation/doc.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 508b6b30baa..9e4a8df6440 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - Support Go 1.19. Include compatibility testing and document support. (#3077) - Upgrade go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 (#3107) +- Add an `Attribute` field to the `Scope` type in `go.opentelemetry.io/otel/sdk/instrumentation`. (#3131) +- Add the `WithScopeAttributes` `TracerOption` to the `go.opentelemetry.io/otel/trace` package. (#3131) +- Add the `WithScopeAttributes` `MeterOption` to the `go.opentelemetry.io/otel/metric` package. (#3132) ### Changed @@ -20,6 +23,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - The exponential histogram mapping functions have been updated with exact upper-inclusive boundary support following the [corresponding specification change](https://github.com/open-telemetry/opentelemetry-specification/pull/2633). (#2982) +- Attempting to start a span with a nil `context` will no longer cause a panic. (#3110) +- Export scope attributes for all exporters provided by `go.opentelemetry.io/otel/exporters/otlp/otlptrace`. (#3131) ## [1.9.0/0.0.3] - 2022-08-01 diff --git a/bridge/opentracing/bridge_test.go b/bridge/opentracing/bridge_test.go index a64d6f73919..7286bd77823 100644 --- a/bridge/opentracing/bridge_test.go +++ b/bridge/opentracing/bridge_test.go @@ -22,9 +22,11 @@ import ( "testing" ot "github.com/opentracing/opentracing-go" + "github.com/opentracing/opentracing-go/ext" "github.com/stretchr/testify/assert" "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/bridge/opentracing/internal" "go.opentelemetry.io/otel/propagation" "go.opentelemetry.io/otel/trace" ) @@ -425,3 +427,44 @@ func TestBridgeTracer_StartSpan(t *testing.T) { }) } } + +func Test_otTagsToOTelAttributesKindAndError(t *testing.T) { + tracer := internal.NewMockTracer() + sc := &bridgeSpanContext{} + + testCases := []struct { + name string + opt []ot.StartSpanOption + expected trace.SpanKind + }{ + { + name: "client", + opt: []ot.StartSpanOption{ext.SpanKindRPCClient}, + expected: trace.SpanKindClient, + }, + { + name: "server", + opt: []ot.StartSpanOption{ext.RPCServerOption(sc)}, + expected: trace.SpanKindServer, + }, + { + name: "client string", + opt: []ot.StartSpanOption{ot.Tag{Key: "span.kind", Value: "client"}}, + expected: trace.SpanKindClient, + }, + { + name: "server string", + opt: []ot.StartSpanOption{ot.Tag{Key: "span.kind", Value: "server"}}, + expected: trace.SpanKindServer, + }, + } + + for _, tc := range testCases { + t.Run(tc.name, func(t *testing.T) { + b, _ := NewTracerPair(tracer) + + s := b.StartSpan(tc.name, tc.opt...) + assert.Equal(t, s.(*bridgeSpan).otelSpan.(*internal.MockSpan).SpanKind, tc.expected) + }) + } +} diff --git a/exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go b/exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go index 7aaec38d22a..4dcddb17809 100644 --- a/exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go +++ b/exporters/otlp/otlptrace/internal/tracetransform/instrumentation.go @@ -24,7 +24,8 @@ func InstrumentationScope(il instrumentation.Scope) *commonpb.InstrumentationSco return nil } return &commonpb.InstrumentationScope{ - Name: il.Name, - Version: il.Version, + Name: il.Name, + Version: il.Version, + Attributes: Iterator(il.Attributes.Iter()), } } diff --git a/exporters/otlp/otlptrace/internal/tracetransform/instrumentation_test.go b/exporters/otlp/otlptrace/internal/tracetransform/instrumentation_test.go new file mode 100644 index 00000000000..634d1dfaf00 --- /dev/null +++ b/exporters/otlp/otlptrace/internal/tracetransform/instrumentation_test.go @@ -0,0 +1,52 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package tracetransform // import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/internal/tracetransform" + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "go.opentelemetry.io/otel/attribute" + "go.opentelemetry.io/otel/sdk/instrumentation" + commonpb "go.opentelemetry.io/proto/otlp/common/v1" +) + +func TestInstrumentationScope(t *testing.T) { + t.Run("Empty", func(t *testing.T) { + assert.Nil(t, InstrumentationScope(instrumentation.Scope{})) + }) + + t.Run("Mapping", func(t *testing.T) { + var ( + name = "instrumentation name" + version = "v0.1.0" + attr = attribute.NewSet(attribute.String("domain", "trace")) + attrPb = Iterator(attr.Iter()) + ) + expected := &commonpb.InstrumentationScope{ + Name: name, + Version: version, + Attributes: attrPb, + } + actual := InstrumentationScope(instrumentation.Scope{ + Name: name, + Version: version, + SchemaURL: "http://this.is.mapped.elsewhere.com", + Attributes: attr, + }) + assert.Equal(t, expected, actual) + }) +} diff --git a/exporters/stdout/stdoutmetric/example_test.go b/exporters/stdout/stdoutmetric/example_test.go index 8a2528661dd..6dcf163c47f 100644 --- a/exporters/stdout/stdoutmetric/example_test.go +++ b/exporters/stdout/stdoutmetric/example_test.go @@ -142,7 +142,9 @@ func Example() { // { // "Scope": { // "Name": "example", - // "Version": "v0.0.1" + // "Version": "v0.0.1", + // "SchemaURL": "", + // "Attributes": null // }, // "Metrics": [ // { diff --git a/exporters/stdout/stdouttrace/trace_test.go b/exporters/stdout/stdouttrace/trace_test.go index 8f056460cdb..82bd2fcabd7 100644 --- a/exporters/stdout/stdouttrace/trace_test.go +++ b/exporters/stdout/stdouttrace/trace_test.go @@ -185,7 +185,9 @@ func expectedJSON(now time.Time) string { ], "InstrumentationLibrary": { "Name": "", - "Version": "" + "Version": "", + "SchemaURL": "", + "Attributes": null } } ` diff --git a/metric/config.go b/metric/config.go index 621e4c5fcb8..ddadd62f9f9 100644 --- a/metric/config.go +++ b/metric/config.go @@ -14,10 +14,13 @@ package metric // import "go.opentelemetry.io/otel/metric" +import "go.opentelemetry.io/otel/attribute" + // MeterConfig contains options for Meters. type MeterConfig struct { instrumentationVersion string schemaURL string + attributes attribute.Set } // InstrumentationVersion is the version of the library providing instrumentation. @@ -30,6 +33,11 @@ func (cfg MeterConfig) SchemaURL() string { return cfg.schemaURL } +// Attributes returns the scope attribute set of the Meter. +func (t MeterConfig) Attributes() attribute.Set { + return t.attributes +} + // MeterOption is an interface for applying Meter options. type MeterOption interface { // applyMeter is used to set a MeterOption value of a MeterConfig. @@ -67,3 +75,13 @@ func WithSchemaURL(schemaURL string) MeterOption { return config }) } + +// WithScopeAttributes sets the attributes for the scope of a Meter. The +// attributes are stored as an attribute set. Duplicate values are removed, the +// last value is used. +func WithScopeAttributes(attr ...attribute.KeyValue) MeterOption { + return meterOptionFunc(func(cfg MeterConfig) MeterConfig { + cfg.attributes = attribute.NewSet(attr...) + return cfg + }) +} diff --git a/metric/config_test.go b/metric/config_test.go new file mode 100644 index 00000000000..359e14c0603 --- /dev/null +++ b/metric/config_test.go @@ -0,0 +1,69 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package metric // import "go.opentelemetry.io/otel/metric" + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + "go.opentelemetry.io/otel/attribute" +) + +func TestMeterConfig(t *testing.T) { + t.Run("Empty", func(t *testing.T) { + assert.Equal(t, NewMeterConfig(), MeterConfig{}) + }) + + t.Run("InstrumentationVersion", func(t *testing.T) { + v0, v1 := "v0.1.0", "v1.0.0" + + assert.Equal(t, NewMeterConfig( + WithInstrumentationVersion(v0), + ).InstrumentationVersion(), v0) + + assert.Equal(t, NewMeterConfig( + WithInstrumentationVersion(v0), + WithInstrumentationVersion(v1), + ).InstrumentationVersion(), v1, "last option has precedence") + }) + + t.Run("SchemaURL", func(t *testing.T) { + s120 := "https://opentelemetry.io/schemas/1.2.0" + s130 := "https://opentelemetry.io/schemas/1.3.0" + + assert.Equal(t, NewMeterConfig( + WithSchemaURL(s120), + ).SchemaURL(), s120) + + assert.Equal(t, NewMeterConfig( + WithSchemaURL(s120), + WithSchemaURL(s130), + ).SchemaURL(), s130, "last option has precedence") + }) + + t.Run("Attributes", func(t *testing.T) { + one, two := attribute.Int("key", 1), attribute.Int("key", 2) + + assert.Equal(t, NewMeterConfig( + WithScopeAttributes(one, two), + ).Attributes(), attribute.NewSet(two), "last attribute is used") + + assert.Equal(t, NewMeterConfig( + WithScopeAttributes(two), + WithScopeAttributes(one), + ).Attributes(), attribute.NewSet(one), "last option has precedence") + }) +} diff --git a/metric/meter.go b/metric/meter.go index 21fc1c499fb..b548405353c 100644 --- a/metric/meter.go +++ b/metric/meter.go @@ -24,15 +24,50 @@ import ( "go.opentelemetry.io/otel/metric/instrument/syncint64" ) -// MeterProvider provides access to named Meter instances, for instrumenting -// an application or library. +// MeterProvider provides Meters that are used by instrumentation code to +// create instruments that measure code operations. +// +// A MeterProvider is the collection destination of all measurements made from +// instruments the provided Meters created, it represents a unique telemetry +// collection pipeline. How that pipeline is defined, meaning how those +// measurements are collected, processed, and where they are exported, depends +// on its implementation. Instrumentation authors do not need to define this +// implementation, rather just use the provided Meters to instrument code. +// +// Commonly, instrumentation code will accept a MeterProvider implementation at +// runtime from its users or it can simply use the globally registered one (see +// https://pkg.go.dev/go.opentelemetry.io/otel/metric/global#MeterProvider). +// +// Warning: methods may be added to this interface in minor releases. type MeterProvider interface { - // Meter creates an instance of a `Meter` interface. The instrumentationName - // must be the name of the library providing instrumentation. This name may - // be the same as the instrumented code only if that code provides built-in - // instrumentation. If the instrumentationName is empty, then a - // implementation defined default name will be used instead. - Meter(instrumentationName string, opts ...MeterOption) Meter + // Meter returns a unique Meter scoped to be used by instrumentation code + // to measure code operations. The scope and identity of that + // instrumentation code is uniquely defined by the name and options passed. + // + // The passed name needs to uniquely identify instrumentation code. + // Therefore, it is recommended that name is the Go package name of the + // library providing instrumentation (note: not the code being + // instrumented). Instrumentation libraries can have multiple versions, + // therefore, the WithInstrumentationVersion option should be used to + // distinguish these different codebases. Additionally, instrumentation + // libraries may sometimes use metric measurements to communicate different + // domains of code operations data (i.e. using different Meters to + // communicate user experience and back-end operations). If this is the + // case, the WithScopeAttributes option should be used to uniquely identify + // Meters that handle the different domains of code operations data. + // + // If the same name and options are passed multiple times, the same Meter + // will be returned (it is up to the implementation if this will be the + // same underlying instance of that Meter or not). It is not necessary to + // call this multiple times with the same name and options to get an + // up-to-date Meter. All implementations will ensure any MeterProvider + // configuration changes are propagated to all provided Meters. + // + // If name is empty, then an implementation defined default name will be + // used instead. + // + // This method is safe to call concurrently. + Meter(name string, options ...MeterOption) Meter } // Meter provides access to instrument instances for recording metrics. diff --git a/sdk/instrumentation/doc.go b/sdk/instrumentation/doc.go new file mode 100644 index 00000000000..6e923acab43 --- /dev/null +++ b/sdk/instrumentation/doc.go @@ -0,0 +1,24 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package instrumentation provides types to represent the code libraries that +// provide OpenTelemetry instrumentation. These types are used in the +// OpenTelemetry signal pipelines to identify the source of telemetry. +// +// See +// https://github.com/open-telemetry/oteps/blob/d226b677d73a785523fe9b9701be13225ebc528d/text/0083-component.md +// and +// https://github.com/open-telemetry/oteps/blob/d226b677d73a785523fe9b9701be13225ebc528d/text/0201-scope-attributes.md +// for more information. +package instrumentation // import "go.opentelemetry.io/otel/sdk/instrumentation" diff --git a/sdk/instrumentation/library.go b/sdk/instrumentation/library.go index 246873345de..39f025a1715 100644 --- a/sdk/instrumentation/library.go +++ b/sdk/instrumentation/library.go @@ -12,13 +12,6 @@ // See the License for the specific language governing permissions and // limitations under the License. -/* -Package instrumentation provides an instrumentation library structure to be -passed to both the OpenTelemetry Tracer and Meter components. - -For more information see -[this](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md). -*/ package instrumentation // import "go.opentelemetry.io/otel/sdk/instrumentation" // Library represents the instrumentation library. diff --git a/sdk/instrumentation/scope.go b/sdk/instrumentation/scope.go index bbbed01c5b3..3001b6cc907 100644 --- a/sdk/instrumentation/scope.go +++ b/sdk/instrumentation/scope.go @@ -12,16 +12,16 @@ // See the License for the specific language governing permissions and // limitations under the License. -/* -Package instrumentation provides an instrumentation scope structure to be -passed to both the OpenTelemetry Tracer and Meter components. - -For more information see -[this](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md). -*/ package instrumentation // import "go.opentelemetry.io/otel/sdk/instrumentation" -// Scope represents the instrumentation scope. +import "go.opentelemetry.io/otel/attribute" + +// Scope represents the instrumentation source of OpenTelemetry data. +// +// Code that uses OpenTelemetry APIs or data-models to produce telemetry needs +// to be identifiable by the receiver of that data. A Scope is used for this +// purpose, it uniquely identifies that code as the source and the extent to +// which it is relevant. type Scope struct { // Name is the name of the instrumentation scope. This should be the // Go package name of that scope. @@ -29,5 +29,14 @@ type Scope struct { // Version is the version of the instrumentation scope. Version string // SchemaURL of the telemetry emitted by the scope. - SchemaURL string `json:",omitempty"` + SchemaURL string + // Attributes describe the unique attributes of an instrumentation scope. + // + // These attributes are used to differentiate an instrumentation scope when + // it emits data that belong to different domains. For example, if both + // profiling data and client-side data are emitted as log records from the + // same instrumentation library, they may need to be differentiated by a + // telemetry receiver. In that case, these attributes are used to scope and + // differentiate the data. + Attributes attribute.Set } diff --git a/sdk/trace/provider.go b/sdk/trace/provider.go index 3c8abb8c1aa..7498017903a 100644 --- a/sdk/trace/provider.go +++ b/sdk/trace/provider.go @@ -142,9 +142,10 @@ func (p *TracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.T name = defaultTracerName } is := instrumentation.Scope{ - Name: name, - Version: c.InstrumentationVersion(), - SchemaURL: c.SchemaURL(), + Name: name, + Version: c.InstrumentationVersion(), + SchemaURL: c.SchemaURL(), + Attributes: c.Attributes(), } t, ok := p.namedTracer[is] if !ok { @@ -153,7 +154,13 @@ func (p *TracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.T instrumentationScope: is, } p.namedTracer[is] = t - global.Info("Tracer created", "name", name, "version", c.InstrumentationVersion(), "schemaURL", c.SchemaURL()) + global.Info( + "Tracer created", + "name", name, + "version", c.InstrumentationVersion(), + "schemaURL", c.SchemaURL(), + "attributes", c.Attributes(), + ) } return t } @@ -241,10 +248,7 @@ func (p *TracerProvider) Shutdown(ctx context.Context) error { if !ok { return fmt.Errorf("failed to load span processors") } - if len(spss) == 0 { - return nil - } - + var retErr error for _, sps := range spss { select { case <-ctx.Done(): @@ -257,10 +261,15 @@ func (p *TracerProvider) Shutdown(ctx context.Context) error { err = sps.sp.Shutdown(ctx) }) if err != nil { - return err + if retErr == nil { + retErr = err + } else { + // Poor man's list of errors + retErr = fmt.Errorf("%v; %v", retErr, err) + } } } - return nil + return retErr } // TracerProviderOption configures a TracerProvider. diff --git a/sdk/trace/provider_test.go b/sdk/trace/provider_test.go index 39caf5a91df..6ec3df6794d 100644 --- a/sdk/trace/provider_test.go +++ b/sdk/trace/provider_test.go @@ -72,6 +72,28 @@ func TestFailedProcessorShutdown(t *testing.T) { assert.Equal(t, err, spErr) } +func TestFailedProcessorsShutdown(t *testing.T) { + stp := NewTracerProvider() + spErr1 := errors.New("basic span processor shutdown failure1") + spErr2 := errors.New("basic span processor shutdown failure2") + sp1 := &basicSpanProcesor{ + running: true, + injectShutdownError: spErr1, + } + sp2 := &basicSpanProcesor{ + running: true, + injectShutdownError: spErr2, + } + stp.RegisterSpanProcessor(sp1) + stp.RegisterSpanProcessor(sp2) + + err := stp.Shutdown(context.Background()) + assert.Error(t, err) + assert.EqualError(t, err, "basic span processor shutdown failure1; basic span processor shutdown failure2") + assert.False(t, sp1.running) + assert.False(t, sp2.running) +} + func TestFailedProcessorShutdownInUnregister(t *testing.T) { handler.Reset() stp := NewTracerProvider() diff --git a/sdk/trace/trace_test.go b/sdk/trace/trace_test.go index 8d95782115b..8badccc4240 100644 --- a/sdk/trace/trace_test.go +++ b/sdk/trace/trace_test.go @@ -363,6 +363,16 @@ func TestStartSpanWithParent(t *testing.T) { } } +// Test we get a successful span as a new root if a nil context is sent in, as opposed to a panic. +// See https://github.com/open-telemetry/opentelemetry-go/issues/3109 +func TestStartSpanWithNilContext(t *testing.T) { + tp := NewTracerProvider() + tr := tp.Tracer("NoPanic") + + // nolint:staticcheck // no nil context, but that's the point of the test. + assert.NotPanics(t, func() { tr.Start(nil, "should-not-panic") }) +} + func TestStartSpanNewRootNotSampled(t *testing.T) { alwaysSampleTp := NewTracerProvider() sampledTr := alwaysSampleTp.Tracer("AlwaysSampled") @@ -901,6 +911,8 @@ func TestSetSpanStatusWithoutMessageWhenStatusIsNotError(t *testing.T) { func cmpDiff(x, y interface{}) string { return cmp.Diff(x, y, cmp.AllowUnexported(snapshot{}), + cmp.AllowUnexported(attribute.Set{}), + cmp.AllowUnexported(attribute.Distinct{}), cmp.AllowUnexported(attribute.Value{}), cmp.AllowUnexported(Event{}), cmp.AllowUnexported(trace.TraceState{})) diff --git a/sdk/trace/tracer.go b/sdk/trace/tracer.go index f4a1f96f3d6..7b11fc465c6 100644 --- a/sdk/trace/tracer.go +++ b/sdk/trace/tracer.go @@ -37,6 +37,11 @@ var _ trace.Tracer = &tracer{} func (tr *tracer) Start(ctx context.Context, name string, options ...trace.SpanStartOption) (context.Context, trace.Span) { config := trace.NewSpanStartConfig(options...) + if ctx == nil { + // Prevent trace.ContextWithSpan from panicking. + ctx = context.Background() + } + // For local spans created by this SDK, track child span count. if p := trace.SpanFromContext(ctx); p != nil { if sdkSpan, ok := p.(*recordingSpan); ok { diff --git a/trace/config.go b/trace/config.go index f058cc781e0..a7b7eab2172 100644 --- a/trace/config.go +++ b/trace/config.go @@ -24,7 +24,8 @@ import ( type TracerConfig struct { instrumentationVersion string // Schema URL of the telemetry emitted by the Tracer. - schemaURL string + schemaURL string + attributes attribute.Set } // InstrumentationVersion returns the version of the library providing instrumentation. @@ -37,6 +38,11 @@ func (t *TracerConfig) SchemaURL() string { return t.schemaURL } +// Attributes returns the scope attribute set of the Tracer. +func (t *TracerConfig) Attributes() attribute.Set { + return t.attributes +} + // NewTracerConfig applies all the options to a returned TracerConfig. func NewTracerConfig(options ...TracerOption) TracerConfig { var config TracerConfig @@ -314,3 +320,13 @@ func WithSchemaURL(schemaURL string) TracerOption { return cfg }) } + +// WithScopeAttributes sets the attributes for the scope of a Tracer. The +// attributes are stored as an attribute set. Duplicate values are removed, the +// last value is used. +func WithScopeAttributes(attr ...attribute.KeyValue) TracerOption { + return tracerOptionFunc(func(cfg TracerConfig) TracerConfig { + cfg.attributes = attribute.NewSet(attr...) + return cfg + }) +} diff --git a/trace/config_test.go b/trace/config_test.go index a4cafcbcd09..d46a8e137c6 100644 --- a/trace/config_test.go +++ b/trace/config_test.go @@ -211,6 +211,7 @@ func TestTracerConfig(t *testing.T) { v1 := "semver:0.0.1" v2 := "semver:1.0.0" schemaURL := "https://opentelemetry.io/schemas/1.2.0" + one, two := attribute.Int("key", 1), attribute.Int("key", 2) tests := []struct { options []TracerOption expected TracerConfig @@ -246,6 +247,24 @@ func TestTracerConfig(t *testing.T) { schemaURL: schemaURL, }, }, + + { + []TracerOption{ + WithScopeAttributes(one, two), + }, + TracerConfig{ + attributes: attribute.NewSet(two), + }, + }, + { + []TracerOption{ + WithScopeAttributes(two), + WithScopeAttributes(one), + }, + TracerConfig{ + attributes: attribute.NewSet(one), + }, + }, } for _, test := range tests { config := NewTracerConfig(test.options...) diff --git a/trace/trace.go b/trace/trace.go index 3e009873219..97f3d83855b 100644 --- a/trace/trace.go +++ b/trace/trace.go @@ -503,17 +503,48 @@ type Tracer interface { Start(ctx context.Context, spanName string, opts ...SpanStartOption) (context.Context, Span) } -// TracerProvider provides access to instrumentation Tracers. +// TracerProvider provides Tracers that are used by instrumentation code to +// trace computational workflows. +// +// A TracerProvider is the collection destination of all Spans from Tracers it +// provides, it represents a unique telemetry collection pipeline. How that +// pipeline is defined, meaning how those Spans are collected, processed, and +// where they are exported, depends on its implementation. Instrumentation +// authors do not need to define this implementation, rather just use the +// provided Tracers to instrument code. +// +// Commonly, instrumentation code will accept a TracerProvider implementation +// at runtime from its users or it can simply use the globally registered one +// (see https://pkg.go.dev/go.opentelemetry.io/otel#GetTracerProvider). // // Warning: methods may be added to this interface in minor releases. type TracerProvider interface { - // Tracer creates an implementation of the Tracer interface. - // The instrumentationName must be the name of the library providing - // instrumentation. This name may be the same as the instrumented code - // only if that code provides built-in instrumentation. If the - // instrumentationName is empty, then a implementation defined default - // name will be used instead. + // Tracer returns a unique Tracer scoped to be used by instrumentation code + // to trace computational workflows. The scope and identity of that + // instrumentation code is uniquely defined by the name and options passed. + // + // The passed name needs to uniquely identify instrumentation code. + // Therefore, it is recommended that name is the Go package name of the + // library providing instrumentation (note: not the code being + // instrumented). Instrumentation libraries can have multiple versions, + // therefore, the WithInstrumentationVersion option should be used to + // distinguish these different codebases. Additionally, instrumentation + // libraries may sometimes use traces to communicate different domains of + // workflow data (i.e. using spans to communicate workflow events only). If + // this is the case, the WithScopeAttributes option should be used to + // uniquely identify Tracers that handle the different domains of workflow + // data. + // + // If the same name and options are passed multiple times, the same Tracer + // will be returned (it is up to the implementation if this will be the + // same underlying instance of that Tracer or not). It is not necessary to + // call this multiple times with the same name and options to get an + // up-to-date Tracer. All implementations will ensure any TracerProvider + // configuration changes are propagated to all provided Tracers. + // + // If name is empty, then an implementation defined default name will be + // used instead. // - // This method must be concurrency safe. - Tracer(instrumentationName string, opts ...TracerOption) Tracer + // This method is safe to call concurrently. + Tracer(name string, options ...TracerOption) Tracer } diff --git a/website_docs/_index.md b/website_docs/_index.md index a21cc50329d..a1ab8723779 100644 --- a/website_docs/_index.md +++ b/website_docs/_index.md @@ -19,7 +19,7 @@ This is the OpenTelemetry for Go documentation. OpenTelemetry is an observabilit The current status of the major functional components for OpenTelemetry Go is as follows: -| Tracing | Metrics | Logging | +| Traces | Metrics | Logs | | ------- | ------- | ------- | | Stable | Alpha | Not Yet Implemented |