initialize static method

void initialize({ String endpoint = OTelFactory.defaultEndpoint, String? serviceName = OTelAPI.defaultServiceName, String? serviceVersion = OTelAPI.defaultServiceVersion, OTelFactoryCreationFunction? oTelFactoryCreationFunction, })

Typically developers will want to initialize OTel (the SDK), and not OTelAPI (the no-op API). The initialize method must be called before any other methods.

The global default TracerProvider and it's tracers will use the provided parameters. endpoint is a URL. The OTel spec's default exporter protocol is http/protobuf (OTLP/HTTP) on port 4318, so http://localhost:4318 is the local-collector default. Use http://localhost:4317 only when you've explicitly switched to the gRPC protocol. serviceName SHOULD uniquely identify the instrumentation scope, such as the instrumentation library (e.g. @dart/dartastic_opentelemetry_api), package, module or class name. serviceVersion defaults to the matching OTel spec version plus a release version of this library, currently 1.11.0.0 oTelFactoryCreationFunction defaults to a function that constructs the noop OTelAPIFactory as required by the specification. A factory method is required for serialization across execution contexts (isolates). Using OTel.initialize in the dartastic_opentelemetry library sets this factory to an SDK factory, which is the typical usage.

Implementation

static void initialize(
    {String endpoint = OTelFactory.defaultEndpoint,
    String? serviceName = OTelAPI.defaultServiceName,
    String? serviceVersion = OTelAPI.defaultServiceVersion,
    OTelFactoryCreationFunction? oTelFactoryCreationFunction}) {
  // The no-op API factory auto-installs when API code (e.g. Context.current)
  // runs before initialize(), per spec. An installed API factory is
  // replaceable — only a real (SDK) factory means initialization already
  // happened and must not be silently discarded.
  final existingFactory = OTelFactory.otelFactory;
  if (existingFactory != null && !existingFactory.isAPIFactory) {
    throw StateError(
        'OTelAPI can only be initialized once. If you need multiple endpoints or service names or versions create a named TracerProvider');
  }
  if (existingFactory != null && OTelLog.isDebug()) {
    OTelLog.debug(
        'OTelAPI.initialize: replacing the installed no-op API factory '
        'with the configured API factory. API objects obtained before '
        'initialize() remain no-ops.');
  }
  if (endpoint.isEmpty) {
    throw ArgumentError(
        'endpoint must not be empty.  Since the API (but not the SDK) uses noop processors by default, this can be any url for the API such as http://localhost:4318.');
  }
  if (serviceName == null || serviceName.isEmpty) {
    throw ArgumentError('serviceName must not be null or the empty string.');
  }
  if (serviceVersion == null || serviceVersion.isEmpty) {
    throw ArgumentError(
        'serviceVersion must not be null or the empty string.');
  }
  final factoryFactory =
      oTelFactoryCreationFunction ?? otelApiFactoryFactoryFunction;
  OTelFactory.otelFactory = factoryFactory(
      apiEndpoint: endpoint,
      apiServiceName: serviceName,
      apiServiceVersion: serviceVersion);
}