On browser setting window.OTEL_SERVICE_NAME does not populate service.name

[shanshanzhu]

Setting window.OTEL_SERVICE_NAME should populate service.name. Or please document the correct way to populate service.name in browser request (Not node)

[theletterf]

@shanshanzhu What language is this related to?

[shanshanzhu]

@theletterf Javascript run on browser (not nodeJS)

[theletterf]

@open-telemetry/javascript-approvers Could you have a look?

@shanshanzhu Could you provide the specific doc where this appears?

[trentm]

(Warning: I don't know the Web side of the OTel code very well, so I might get this wrong.)

The automatic handling of OTEL_SERVICE_NAME and some other environment variables is specified only for an OTel "SDK". There currently is not a "WebSDK" for web JS usage -- at least not yet -- so there is no convenient usage that will automatically pick up the "service name".

That means you have to do it manually.

Starting from https://opentelemetry.io/docs/languages/js/getting-started/browser/
the OTel setup code for browser starts with something like:

// ...
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';

const provider = new WebTracerProvider();
// ...

That WebTracerProvider takes a TracerConfig: https://github.com/open-telemetry/opentelemetry-js/blob/14d086a234416080a111aae7d45682f08b80d92e/packages/opentelemetry-sdk-trace-web/src/WebTracerProvider.ts#L32-L37

TracerConfig takes a resource property: https://github.com/open-telemetry/opentelemetry-js/blob/14d086a234416080a111aae7d45682f08b80d92e/packages/opentelemetry-sdk-trace-base/src/types.ts#L38

The "service name" for OpenTelemetry data is defined in a "resource" object.
Without a convenient "SDK" interface, the @opentelemetry/resources pacakge provides the interfaces to create a resource.
https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-resources/#readme

Option 1 is to manually create a resource:

// ...
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { Resource } from '@opentelemetry/resources';

const resource = new Resource({
    'service.name': 'my-service',
});
const provider = new WebTracerProvider({ resource });
// ...

Option 2 is to use the (not documented in its README) detectResourcesSync() and the envDetectorSync export which reads the "environment variables". Something like this (untested):

import { envDetectorSync, detectResourcesSync } from '@opentelemetry/resources';

const resource = detectResourcesSync({detectors: [envDetectorSync]});
// ...

I put "environment variables" in quotes, because the concept isn't really a thing in a browser. However, for now at least, the OTel JS browser code supports reading OTEL_... properties from the globalThis object in the browser (which is the same as the "window" object, I believe).

[trentm]

Yes, this should definitely be documented. I feel a little out of my depth tackling the Web JS docs.

I suppose for a start we could add some reference docs to https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-web/README.md mentioning use of the resource to set service name.

Likewise the https://opentelemetry.io/docs/languages/js/getting-started/browser/ page should mention setting service name. Setting service name is so important to using OTel data meaningfully that I feel like I may be missing something in these docs or in the code defaults.

[svrnm]

@trentm who would be the best person from the JS SIG to help with that?

[svrnm]

@open-telemetry/javascript-approvers PTAL, is this something we can fix?

[pichlermarc]

@svrnm - sorry just saw this:

If I had to recommend a way, I'd recommend Option 1 that @trentm mentioned, doing it manually:

// ...
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { Resource } from '@opentelemetry/resources';

const resource = new Resource({
    'service.name': 'my-service',
});
const provider = new WebTracerProvider({ resource });
// ...

I talked to the other JS SIG Maintainers recently, and we concluded that the whole window.ENV_VAR_HERE does not really make too much sense and is quite confusing. We concluded that we want to remove that feature at some point as it just offers a second way to do things that has no benefits over the conventional approach from @trentm's Option 1.

[svrnm]

thanks, so the best way to solve this is adding these instructions to the getting started guide I guess?

[trentm]

so the best way to solve this is adding these instructions to the getting started guide I guess?

Yes, I think so.

And then, I guess https://opentelemetry.io/docs/languages/js/resources/#adding-resources-with-environment-variables should be made clear that it is talking about Node.js and not JS in the browser.