feat: Add Sentry Exporter

cmd/otelcontribcol/components.go

@@ -30,6 +30,7 @@ import (
 	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/lightstepexporter"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/newrelicexporter"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/sapmexporter"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/sentryexporter"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/signalfxexporter"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/splunkhecexporter"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/stackdriverexporter"
@@ -106,6 +107,7 @@ func components() (component.Factories, error) {
 		&splunkhecexporter.Factory{},
 		elasticexporter.NewFactory(),
 		&alibabacloudlogserviceexporter.Factory{},
+		sentryexporter.NewFactory(),
 	}
 	for _, exp := range factories.Exporters {
 		exporters = append(exporters, exp)

exporter/sentryexporter/Makefile

@@ -0,0 +1 @@
+include ../../Makefile.Common

exporter/sentryexporter/README.md

@@ -0,0 +1,45 @@
+# Sentry Exporter
+
+The Sentry Exporter allows you to send traces to [Sentry](https://sentry.io/).
+
+For more details about distributed tracing in Sentry, please view [our documentation](https://docs.sentry.io/performance-monitoring/distributed-tracing/).
+
+The following configuration options are supported:
+
+- `dsn`: The DSN tells the exporter where to send the events. You can find a Sentry project DSN in the “Client Keys” section of the “Project Settings” section of a Sentry project.
+
+Example:
+
+```yaml
+exporters:
+  sentry:
+    dsn: https://key@host/path/42
+```
+
+See the [docs](./docs/transformation.md) for more details on how this transformation is working.
+
+### Known Limitations
+
+Currently, Sentry Tracing leverages a transaction-based system, where a transaction contains one or more spans. The exporter will try to group spans from a trace under one or more transactions based on internal heuristics, but this may lead to the creation of transactions that contain only one or two spans. These transactions will still be viewable and associated under a single trace in the Sentry UI.
+
+One consequence of this result is that very large traces with a large number of spans (500+) and only one root span might be split up into a large number of transactions. There are no current ways to work around this.
+
+### Associating with Sentry Errors
+
+To associate OpenTelemetry spans with Sentry errors, you can set a trace context on the error event. Whenever you start a new trace, you can update the scope to reference a new `trace_id`.
+
+An example with Python but applies to any language that supports a Sentry SDK.
+
+```py
+from sentry_sdk import configure_scope
+
+with start_otel_span("start") as span:
+  ctx = span.get_context()
+  with configure_scope() as scope:
+    scope.set_context("trace", {"trace_id": ctx.trace_id})
+
+  with start_otel_span("child"):
+    # ...
+```
+
+Now if traces are ingested into Sentry, you can associate them to errors that occurred during the trace using the `trace_id`. For a full list of the Sentry SDKs and platforms, please check the [Sentry documentation](https://docs.sentry.io/platforms/).

exporter/sentryexporter/config.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 sentryexporter
+
+import "go.opentelemetry.io/collector/config/configmodels"
+
+// Config defines the configuration for the Sentry Exporter.
+type Config struct {
+	configmodels.ExporterSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct.
+	// DSN to report transaction to Sentry. If the DSN is not set, no trace will be sent to Sentry.
+	DSN string `mapstructure:"dsn"`
+}

exporter/sentryexporter/config_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 sentryexporter
+
+import (
+	"path"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/collector/component/componenttest"
+	"go.opentelemetry.io/collector/config/configmodels"
+	"go.opentelemetry.io/collector/config/configtest"
+)
+
+func TestLoadConfig(t *testing.T) {
+	factories, err := componenttest.ExampleComponents()
+	assert.Nil(t, err)
+
+	factory := NewFactory()
+	factories.Exporters[configmodels.Type(typeStr)] = factory
+	cfg, err := configtest.LoadConfigFile(
+		t, path.Join(".", "testdata", "config.yaml"), factories,
+	)
+
+	require.NoError(t, err)
+	require.NotNil(t, cfg)
+
+	e0 := cfg.Exporters["sentry"]
+	assert.Equal(t, e0, factory.CreateDefaultConfig())
+
+	e1 := cfg.Exporters["sentry/2"]
+	assert.Equal(t, e1, &Config{
+		ExporterSettings: configmodels.ExporterSettings{
+			NameVal: "sentry/2",
+			TypeVal: "sentry",
+		},
+		DSN: "https://key@host/path/42",
+	})
+}

exporter/sentryexporter/docs/transformation.md

@@ -0,0 +1,47 @@
+# OpenTelemetry to Sentry Transformation
+
+This document aims to define the transformations between an OpenTelemetry span and a Sentry Span. It will also describe how a Sentry transaction is created from a set of Sentry spans.
+
+## Spans
+
+The interface for a Sentry Span can be found [here](https://develop.sentry.dev/sdk/event-payloads/span/)
+
+| Sentry              | OpenTelemetry                           | Notes                                                                                                             |
+| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Span.TraceID        | Span.TraceID                            |                                                                                                                   |
+| Span.SpanID         | Span.SpanID                             |                                                                                                                   |
+| Span.ParentSpanID   | Span.ParentSpanID                       | If a span does not have a parent span ID, it is a root span (considered the start of a new transaction in Sentry) |
+| Span.Description    | Span.Name, Span.Attributes, Span.Kind   | The span description is decided using OpenTelemetry Semantic Conventions                                          |
+| Span.Op             | Span.Name, Span.Attributes, Span.Kind   | The span op is decided using OpenTelemetry Semantic Conventions                                                   |
+| Span.Tags           | Span.Attributes, Span.Kind, Span.Status | The otel span status message and span kind are stored as tags on the Sentry span                                  |
+| Span.StartTimestamp | span.StartTime                          |                                                                                                                   |
+| Span.EndTimestamp   | span.EndTime                            |                                                                                                                   |
+| Span.Status         | Span.Status                             |                                                                                                                   |
+
+As can be seen by the table above, the OpenTelemetry span and Sentry span map fairly reasonably. Currently the OpenTelemtry `Span.Link` and `Span.TraceState` properties are not used when constructing a `SentrySpan`
+
+## Transactions
+
+To ingest spans into Sentry, they must be sorted into transactions, which is made up of a root span and it's corresponding child spans, along with useful metadata.
+
+Long-running traces may be split up into different transactions. This will still appear as a single trace in the Sentry UI.
+
+### Implementation
+
+We first iterate through all spans in a trace to figure out which spans are root spans. As with our definition, this can be easily done by just checking for an empty parent span id. If a root span is found, we can create a new transaction. Along the way, if we find any children that belong to the DAG under that root span, we can assign them to that transaction.
+
+After this first iteration, we are left with two structures, an array of transactions, and an array of orphan spans, which we could not classify under a transaction in the first pass.
+
+We can then try again to classify these orphan spans, but if not possible, we can assume these orphan spans to be a root span (as we could not find their parent in the trace). Those root spans generated from orphan spans can be also be then used to create their respective transactions.
+
+The interface for a Sentry Transaction can be found [here](https://develop.sentry.dev/sdk/event-payloads/transaction/)
+
+| Sentry                        | Used to generate                               |
+| ----------------------------- | ---------------------------------------------- |
+| Transaction.Contexts["trace"] | RootSpan.TraceID, RootSpan.SpanID, RootSpan.Op |
+| Transaction.Spans             | ChildSpans                                     |
+| Transaction.Sdk.Name          | `sentry.opentelemetry`                         |
+| Transaction.Tags              | Resource.Attributes, RootSpan.Tags             |
+| Transaction.StartTimestamp    | RootSpan.StartTimestamp                        |
+| Transaction.Timestamp         | RootSpan.EndTimestamp                          |
+| Transaction.Transaction       | RootSpan.Description                           |

exporter/sentryexporter/factory.go

@@ -0,0 +1,61 @@
+// 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 sentryexporter
+
+import (
+	"context"
+	"fmt"
+
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/config/configmodels"
+	"go.opentelemetry.io/collector/exporter/exporterhelper"
+)
+
+const (
+	typeStr = "sentry"
+)
+
+// NewFactory creates a factory for Sentry exporter.
+func NewFactory() component.ExporterFactory {
+	return exporterhelper.NewFactory(
+		typeStr,
+		createDefaultConfig,
+		exporterhelper.WithTraces(createTraceExporter),
+	)
+}
+
+func createDefaultConfig() configmodels.Exporter {
+	return &Config{
+		ExporterSettings: configmodels.ExporterSettings{
+			TypeVal: typeStr,
+			NameVal: typeStr,
+		},
+	}
+}
+
+func createTraceExporter(
+	_ context.Context,
+	params component.ExporterCreateParams,
+	config configmodels.Exporter,
+) (component.TraceExporter, error) {
+	sentryConfig, ok := config.(*Config)
+	if !ok {
+		return nil, fmt.Errorf("unexpected config type: %T", config)
+	}
+
+	// Create exporter based on sentry config.
+	exp, err := CreateSentryExporter(sentryConfig)
+	return exp, err
+}

exporter/sentryexporter/factory_test.go

@@ -0,0 +1,49 @@
+// 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 sentryexporter
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/config/configcheck"
+	"go.uber.org/zap"
+)
+
+func TestCreateDefaultConfig(t *testing.T) {
+	factory := NewFactory()
+	cfg := factory.CreateDefaultConfig()
+	assert.NotNil(t, cfg, "failed to create default config")
+	assert.NoError(t, configcheck.ValidateConfig(cfg))
+}
+
+func TestCreateExporter(t *testing.T) {
+	factory := NewFactory()
+	assert.Equal(t, typeStr, string(factory.Type()))
+
+	cfg := factory.CreateDefaultConfig()
+	eCfg := cfg.(*Config)
+	params := component.ExporterCreateParams{Logger: zap.NewNop()}
+
+	te, err := factory.CreateTraceExporter(context.Background(), params, eCfg)
+	assert.Nil(t, err)
+	assert.NotNil(t, te, "failed to create trace exporter")
+
+	me, err := factory.CreateMetricsExporter(context.Background(), params, eCfg)
+	assert.Error(t, err)
+	assert.Nil(t, me)
+}

exporter/sentryexporter/go.mod

@@ -0,0 +1,13 @@
+module github.com/open-telemetry/opentelemetry-collector-contrib/exporter/sentryexporter
+
+go 1.14
+
+require (
+	github.com/getsentry/sentry-go v0.6.2-0.20200707113342-e7c66ce62664
+	github.com/google/go-cmp v0.5.1
+	github.com/open-telemetry/opentelemetry-proto v0.4.0
+	github.com/stretchr/testify v1.6.1
+	go.opentelemetry.io/collector v0.5.1-0.20200728200651-9cbf43e372f0
+	go.uber.org/zap v1.15.0
+	google.golang.org/grpc/examples v0.0.0-20200728194956-1c32b02682df // indirect
+)