`go.opentelemetry.io/otel/semconv` breaks backwards compatibility guarantees

[katiehockman]

I understand that this issue has been filed in a few places (#2341, open-telemetry/opentelemetry-go-contrib#4261, #4476) but I'd like to file this one to provide some additional context.

We're designing a common library which is called near the top of main() which performs essential initialization steps such as configuring telemetry and initializing shared state. As is pretty standard procedure, this function will panic if any of the essential steps fail since that means the program is not sufficiently set up to run safely.

One such initialization step is to set up the OTel Metric Provider, with code that looks something like this:

res, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName(cfg.serviceName),
		),
	)

if err != nil {
	return err
}

return metric.NewMeterProvider(metric.WithResource(res))

As others have said in previous issues, if we upgrade the go.opentelemetry.io/otel/sdk/metric version in the go.mod without programmatically changing the name of the go.opentelemetry.io/otel/semconv/v1.**.0 module to match the version it requires, then we will get an error. e.g.

conflicting Schema URL: https://opentelemetry.io/schemas/1.34.0 and https://opentelemetry.io/schemas/1.26.0

If it's just us doing this, and we don't have any users of our library, then that can be mitigated. But we have no control over our users upgrading versions of the otel libraries, and those users have no ability to change our code to also upgrade go.opentelemetry.io/otel/semconv at the same time, which leaves us in a tough spot. So now we are stuck choosing between one of these two options:

1. Like with any other essential initialization step that failed, we can panic our Init() function.
   1. The risk with this is that a downstream user of our library may have renovate/dependabot set up which automatically upgrades go.opentelemetry.io/otel/sdk/* and doesn't have a test which executes our Init() function, and it won't panic until production, which is of course not safe.
2. We can log a warning and drop the error.
   1. The risk with this is that there are unknown side effects of a merge error including dropping metrics or overwriting them. If this gets to production where there are monitors or alerts set up which require this metric then it could end up masking real production issues and causing alerts to fire incorrectly or fail to fire when they should.

What's the recommendation here? Or is there a 3rd option I'm not aware of?

The fact that the version name is part of the module name already demonstrates that this is not how Go modules are meant to work and isn't standard operating procedure. This problem stated above is one known reason why this kind of convention isn't supposed to be used in Go.

I'd like to ask that this design be reconsidered to make it easier and safer for clients to use these libraries, and to have this project follow Go's module rules and backwards compatibility guarantees.

[rfuwa14]

To add to this argument, when we suppose semantic convention schema versions are not intended to be managed as go modules, I think there should be a way to control which semconv to use in the sdk packages. The one who defines the resource should own the schema version. Otherwise, updating the otel sdk version would automatically change the used schema.

e.g.

res, err := resource.Merge(
		resource.Default(semconv.SchemaURL),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName(cfg.serviceName),
		),
	)

[pellared]

@katiehockman, please check how https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#example-New is checking and handling the errors. Notice also: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#pkg-variables

I think there should be a way to control which semconv to use in the sdk packages

@rfuwa14, adding support for multiple semconv versions is not something we are planning to do. Maybe we should consider adding some more features to resource to give the possibility to set service name, service version and some other resource attributes which are stable in semantic conventions without users requiring to import the semconv package. I would be grateful if you submit a separate issue for this as I find the current issue as invalid.

[katiehockman]

@pellared thanks for your response.

I looked at https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#example-New, but doesn't this do (2) with the risks associated in my original issue description?

2. We can log a warning and drop the error.
   i. The risk with this is that there are unknown side effects of a merge error including dropping metrics or overwriting them. If this gets to production where there are monitors or alerts set up which require this metric then it could end up masking real production issues and causing alerts to fire incorrectly or fail to fire when they should.

I didn't clarify specifically, but when I said "drop the error" I essentially meant checking for ErrSchemaURLConflict type and dropping that error. However, the docs state "there are unknown side effects of a merge error including dropping metrics or overwriting them" which is my concern.

[lucasoares]

I just ran into the same issue after updating otel 1.38.0, but there's no v1.38.0 directory in semconv...

conflicting Schema URL: https://opentelemetry.io/schemas/1.37.0 and https://opentelemetry.io/schemas/1.38.0

[pellared]

@katiehockman, what docs are you referring to here?

However, the docs state "there are unknown side effects of a merge error including dropping metrics or overwriting them" which is my concern.

Can you please provide a reproducible example when this could happen?

[pellared]

@lucasoares, Go SDK version and OTel SemConv version are different things. At the moment of writing there is no 1.38.0 version of https://github.com/open-telemetry/semantic-conventions/