Skip to content

Commit 0f2943e

Browse files
MrAliasMrAlias
authored
Merge branch 'new_sdk/main' into mvg/new_sdk/instruments_async
2 parents 22d0b29 + 5c9ff25 commit 0f2943e

32 files changed

+3004
-14
lines changed

‎.github/dependabot.yml

+27
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,33 @@ updates:
1919
schedule:
2020
interval: weekly
2121
day: sunday
22+
- package-ecosystem: gomod
23+
directory: /bridge/opencensus
24+
labels:
25+
- dependencies
26+
- go
27+
- Skip Changelog
28+
schedule:
29+
interval: weekly
30+
day: sunday
31+
- package-ecosystem: gomod
32+
directory: /bridge/opencensus/opencensusmetric
33+
labels:
34+
- dependencies
35+
- go
36+
- Skip Changelog
37+
schedule:
38+
interval: weekly
39+
day: sunday
40+
- package-ecosystem: gomod
41+
directory: /bridge/opencensus/test
42+
labels:
43+
- dependencies
44+
- go
45+
- Skip Changelog
46+
schedule:
47+
interval: weekly
48+
day: sunday
2249
- package-ecosystem: gomod
2350
directory: /bridge/opentracing
2451
labels:

‎bridge/opencensus/README.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# OpenCensus Bridge
2+
3+
The OpenCensus Bridge helps facilitate the migration of an application from OpenCensus to OpenTelemetry.
4+
5+
## Caveat about OpenCensus
6+
7+
Installing a metric or tracing bridge will cause OpenCensus telemetry to be exported by OpenTelemetry exporters. Since OpenCensus telemetry uses globals, installing a bridge will result in telemetry collection from _all_ libraries that use OpenCensus, including some you may not expect. For example ([#1928](https://github.com/open-telemetry/opentelemetry-go/issues/1928)), if a client library generates traces with OpenCensus, installing the bridge will cause those traces to be exported by OpenTelemetry.
8+
9+
## Tracing
10+
11+
### The Problem: Mixing OpenCensus and OpenTelemetry libraries
12+
13+
In a perfect world, one would simply migrate their entire go application --including custom instrumentation, libraries, and exporters-- from OpenCensus to OpenTelemetry all at once. In the real world, dependency constraints, third-party ownership of libraries, or other reasons may require mixing OpenCensus and OpenTelemetry libraries in a single application.
14+
15+
However, if you create the following spans in a go application:
16+
17+
```go
18+
ctx, ocSpan := opencensus.StartSpan(context.Background(), "OuterSpan")
19+
defer ocSpan.End()
20+
ctx, otSpan := opentelemetryTracer.Start(ctx, "MiddleSpan")
21+
defer otSpan.End()
22+
ctx, ocSpan := opencensus.StartSpan(ctx, "InnerSpan")
23+
defer ocSpan.End()
24+
```
25+
26+
OpenCensus reports (to OpenCensus exporters):
27+
28+
```
29+
[--------OuterSpan------------]
30+
[----InnerSpan------]
31+
```
32+
33+
OpenTelemetry reports (to OpenTelemetry exporters):
34+
35+
```
36+
[-----MiddleSpan--------]
37+
```
38+
39+
Instead, I would prefer (to a single set of exporters):
40+
41+
```
42+
[--------OuterSpan------------]
43+
[-----MiddleSpan--------]
44+
[----InnerSpan------]
45+
```
46+
47+
### The bridge solution
48+
49+
The bridge implements the OpenCensus trace API using OpenTelemetry. This would cause, for example, a span recorded with OpenCensus' `StartSpan()` method to be equivalent to recording a span using OpenTelemetry's `tracer.Start()` method. Funneling all tracing API calls to OpenTelemetry APIs results in the desired unified span hierarchy.
50+
51+
### User Journey
52+
53+
Starting from an application using entirely OpenCensus APIs:
54+
55+
1. Instantiate OpenTelemetry SDK and Exporters
56+
2. Override OpenCensus' DefaultTracer with the bridge
57+
3. Migrate libraries individually from OpenCensus to OpenTelemetry
58+
4. Remove OpenCensus exporters and configuration
59+
60+
To override OpenCensus' DefaultTracer with the bridge:
61+
62+
```go
63+
import (
64+
octrace "go.opencensus.io/trace"
65+
"go.opentelemetry.io/otel/bridge/opencensus"
66+
"go.opentelemetry.io/otel"
67+
)
68+
69+
tracer := otel.GetTracerProvider().Tracer("bridge")
70+
octrace.DefaultTracer = opencensus.NewTracer(tracer)
71+
```
72+
73+
Be sure to set the `Tracer` name to your instrumentation package name instead of `"bridge"`.
74+
75+
#### Incompatibilities
76+
77+
OpenCensus and OpenTelemetry APIs are not entirely compatible. If the bridge finds any incompatibilities, it will log them. Incompatibilities include:
78+
79+
* Custom OpenCensus Samplers specified during StartSpan are ignored.
80+
* Links cannot be added to OpenCensus spans.
81+
* OpenTelemetry Debug or Deferred trace flags are dropped after an OpenCensus span is created.

‎bridge/opencensus/bridge.go

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package opencensus // import "go.opentelemetry.io/otel/bridge/opencensus"
16+
17+
import (
18+
octrace "go.opencensus.io/trace"
19+
20+
"go.opentelemetry.io/otel/bridge/opencensus/internal"
21+
"go.opentelemetry.io/otel/bridge/opencensus/internal/oc2otel"
22+
"go.opentelemetry.io/otel/bridge/opencensus/internal/otel2oc"
23+
"go.opentelemetry.io/otel/trace"
24+
)
25+
26+
// NewTracer returns an implementation of the OpenCensus Tracer interface which
27+
// uses OpenTelemetry APIs. Using this implementation of Tracer "upgrades"
28+
// libraries that use OpenCensus to OpenTelemetry to facilitate a migration.
29+
func NewTracer(tracer trace.Tracer) octrace.Tracer {
30+
return internal.NewTracer(tracer)
31+
}
32+
33+
// OTelSpanContextToOC converts from an OpenTelemetry SpanContext to an
34+
// OpenCensus SpanContext, and handles any incompatibilities with the global
35+
// error handler.
36+
func OTelSpanContextToOC(sc trace.SpanContext) octrace.SpanContext {
37+
return otel2oc.SpanContext(sc)
38+
}
39+
40+
// OCSpanContextToOTel converts from an OpenCensus SpanContext to an
41+
// OpenTelemetry SpanContext.
42+
func OCSpanContextToOTel(sc octrace.SpanContext) trace.SpanContext {
43+
return oc2otel.SpanContext(sc)
44+
}

‎bridge/opencensus/doc.go

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
// Package opencensus provides a migration bridge from OpenCensus to
16+
// OpenTelemetry. The NewTracer function should be used to create an
17+
// OpenCensus Tracer from an OpenTelemetry Tracer. This Tracer can be use in
18+
// place of any existing OpenCensus Tracer and will generate OpenTelemetry
19+
// spans for traces. These spans will be exported by the OpenTelemetry
20+
// TracerProvider the original OpenTelemetry Tracer came from.
21+
//
22+
// There are known limitations to this bridge:
23+
//
24+
// - The AddLink method for OpenCensus Spans is not compatible with the
25+
// OpenTelemetry Span. No link can be added to an OpenTelemetry Span once it
26+
// is started. Any calls to this method for the OpenCensus Span will result
27+
// in an error being sent to the OpenTelemetry default ErrorHandler.
28+
//
29+
// - The NewContext method of the OpenCensus Tracer cannot embed an OpenCensus
30+
// Span in a context unless that Span was created by that Tracer.
31+
//
32+
// - Conversion of custom OpenCensus Samplers to OpenTelemetry is not
33+
// implemented. An error will be sent to the OpenTelemetry default
34+
// ErrorHandler if this is attempted.
35+
package opencensus // import "go.opentelemetry.io/otel/bridge/opencensus"

‎bridge/opencensus/go.mod

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
module go.opentelemetry.io/otel/bridge/opencensus
2+
3+
go 1.17
4+
5+
require (
6+
go.opencensus.io v0.22.6-0.20201102222123-380f4078db9f
7+
go.opentelemetry.io/otel v1.9.0
8+
go.opentelemetry.io/otel/trace v1.9.0
9+
)
10+
11+
require (
12+
github.com/go-logr/logr v1.2.3 // indirect
13+
github.com/go-logr/stdr v1.2.2 // indirect
14+
github.com/golang/groupcache v0.0.0-20190702054246-869f871628b6 // indirect
15+
)
16+
17+
replace go.opentelemetry.io/otel => ../..
18+
19+
replace go.opentelemetry.io/otel/trace => ../../trace

‎bridge/opencensus/go.sum

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
2+
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
3+
github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
4+
github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
5+
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
6+
github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
7+
github.com/go-logr/logr v1.2.3 h1:2DntVwHkVopvECVRSlL5PSo9eG+cAkDCuckLubN+rq0=
8+
github.com/go-logr/logr v1.2.3/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
9+
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
10+
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
11+
github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
12+
github.com/golang/groupcache v0.0.0-20190702054246-869f871628b6 h1:ZgQEtGgCBiWRM39fZuwSd1LwSqqSW0hOdXCYYDX0R3I=
13+
github.com/golang/groupcache v0.0.0-20190702054246-869f871628b6/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=
14+
github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
15+
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
16+
github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
17+
github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
18+
github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=
19+
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
20+
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
21+
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
22+
github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
23+
github.com/stretchr/testify v1.7.1 h1:5TQK59W5E3v0r2duFAb7P95B6hEeOyEnHRa8MjYSMTY=
24+
go.opencensus.io v0.22.6-0.20201102222123-380f4078db9f h1:IUmbcoP9XyEXW+R9AbrZgDvaYVfTbISN92Y5RIV+Mx4=
25+
go.opencensus.io v0.22.6-0.20201102222123-380f4078db9f/go.mod h1:5pWMHQbX5EPX2/62yrJeAkowc+lfs/XD7Uxpq3pI6kk=
26+
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
27+
golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
28+
golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
29+
golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
30+
golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
31+
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
32+
golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
33+
golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
34+
golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
35+
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
36+
golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
37+
golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
38+
golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
39+
golang.org/x/sync v0.0.0-20190227155943-e225da77a7e6/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
40+
golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
41+
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
42+
golang.org/x/sys v0.0.0-20190502145724-3ef323f4f1fd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
43+
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
44+
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
45+
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
46+
golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
47+
golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
48+
golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
49+
google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
50+
google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
51+
google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
52+
google.golang.org/genproto v0.0.0-20190425155659-357c62f0e4bb/go.mod h1:VzzqZJRnGkLBvHegQrXjBqPurQTc5/KpmUdxsrq26oE=
53+
google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
54+
google.golang.org/grpc v1.20.1/go.mod h1:10oTOabMzJvdu6/UiuZezV6QK5dSlG84ov/aaiqXj38=
55+
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
56+
gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
57+
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
58+
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

‎bridge/opencensus/internal/handler.go

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package internal // import "go.opentelemetry.io/otel/bridge/opencensus/internal"
16+
17+
import "go.opentelemetry.io/otel"
18+
19+
// Handle is the package level function to handle errors. It can be
20+
// overwritten for testing.
21+
var Handle = otel.Handle

‎bridge/opencensus/internal/oc2otel/attributes.go

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Copyright The OpenTelemetry Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package oc2otel // import "go.opentelemetry.io/otel/bridge/opencensus/internal/oc2otel"
16+
17+
import (
18+
octrace "go.opencensus.io/trace"
19+
20+
"go.opentelemetry.io/otel/attribute"
21+
)
22+
23+
func Attributes(attr []octrace.Attribute) []attribute.KeyValue {
24+
otelAttr := make([]attribute.KeyValue, len(attr))
25+
for i, a := range attr {
26+
otelAttr[i] = attribute.KeyValue{
27+
Key: attribute.Key(a.Key()),
28+
Value: AttributeValue(a.Value()),
29+
}
30+
}
31+
return otelAttr
32+
}
33+
34+
func AttributeValue(ocval interface{}) attribute.Value {
35+
switch v := ocval.(type) {
36+
case bool:
37+
return attribute.BoolValue(v)
38+
case int64:
39+
return attribute.Int64Value(v)
40+
case float64:
41+
return attribute.Float64Value(v)
42+
case string:
43+
return attribute.StringValue(v)
44+
default:
45+
return attribute.StringValue("unknown")
46+
}
47+
}

0 commit comments

Comments
 (0)