|
| 1 | +# Upgrade guidelines |
| 2 | + |
| 3 | +## 0.37.x to 0.38.0 |
| 4 | + |
| 5 | +- `@opentelemetry/sdk-node` `NodeSDKConfiguration.defaultAttributes` has been unused and was removed as the concept does not exist in OpenTelemetry anymore |
| 6 | + - Please use `NodeSDKConfiguration.resource` instead. |
| 7 | + |
| 8 | +## 0.35.x to 0.36.0 |
| 9 | + |
| 10 | +- `@opentelemetry/sdk-node` changed `await start()` to now be synchronous |
| 11 | +- `@opentelemetry/sdk-node` changed `await detectResources()` to now be synchronous |
| 12 | + |
| 13 | +## 0.28.x to 0.29.x |
| 14 | + |
| 15 | +- `@opentelemetry/exporter-trace-otlp-http` is now exporting `scopeSpans` instead of `instrumentationLibrarySpans` |
| 16 | + - this exporter now requires collector version `0.48` and up. |
| 17 | +- `@opentelemetry/exporter-metrics-otlp-http` is now exporting `scopeMetrics` instead of `instrumentationLibraryMetrics` |
| 18 | + - this exporter now requires collector version `0.48` and up. |
| 19 | + |
| 20 | +## 0.27.x to 0.28.x |
| 21 | + |
| 22 | +- In `@opentelemetry/exporter-trace-otlp-http`, `OTLPExporterBase._isShutdown` is replaced with `_shutdownOnce`. |
| 23 | + |
| 24 | +## 0.26.x to 0.27.x |
| 25 | + |
| 26 | +Metric and trace exporters are split into separate packages: |
| 27 | + |
| 28 | +- `@opentelemetry/exporter-otlp-http` => `@opentelemetry/exporter-trace-otlp-http` and `@opentelemetry/exporter-metrics-otlp-http` |
| 29 | +- `@opentelemetry/exporter-otlp-grpc` => `@opentelemetry/exporter-trace-otlp-grpc` and `@opentelemetry/exporter-metrics-otlp-grpc` |
| 30 | +- `@opentelemetry/exporter-otlp-proto` => `@opentelemetry/exporter-trace-otlp-proto` and `@opentelemetry/exporter-metrics-otlp-proto` |
| 31 | + |
| 32 | +Metric types are renamed: |
| 33 | + |
| 34 | +- `@openetelemetry/api-metrics` |
| 35 | + - `Meter` |
| 36 | + - `createValueRecorder` => `createHistogram` |
| 37 | + - `createValueObserver` => `createObservableGauge` |
| 38 | + - `createSumObserver` => `createObservableCounter` |
| 39 | + - `createUpDownSumObserver` => `createObservableUpDownCounter` |
| 40 | + - `ValueRecorder` => `Histogram` |
| 41 | + - `ValueObserver` => `ObservableGauge` |
| 42 | + - `SumObserver` => `ObservableCounter` |
| 43 | + - `UpDownSumObserver` => `ObservableUpDownCounter` |
| 44 | + - `ObserverResult` => `ObservableResult` |
| 45 | + - `Observation.observer` => `Observation.observable` |
| 46 | +- `@opentelemetry/sdk-metrics-base` |
| 47 | + - `MetricKind` |
| 48 | + - `VALUE_RECORDER` => `HISTOGRAM` |
| 49 | + - `SUM_OBSERVER` => `OBSERVABLE_COUNTER` |
| 50 | + - `UP_DOWN_SUM_OBSERVER` => `OBSERVABLE_UP_DOWN_COUNTER` |
| 51 | + - `VALUE_OBSERVER` => `OBSERVABLE_GAUGE` |
| 52 | + |
| 53 | +## 0.25.x to 1.x.y |
| 54 | + |
| 55 | +Collector exporter packages and types are renamed: |
| 56 | + |
| 57 | +- `@opentelemetry/exporter-collector` => `@opentelemetry/exporter-otlp-http` |
| 58 | + - `CollectorExporterBase` => `OTLPExporterBase` |
| 59 | + - `CollectorTraceExporter` => `OTLPTraceExporter` |
| 60 | + - `CollectorMetricExporter` => `OTLPMetricExporter` |
| 61 | + - `CollectorExporterBrowserBase` => `OTLPExporterBrowserBase` |
| 62 | + - `CollectorExporterNodeBase` => `OTLPExporterNodeBase` |
| 63 | + - `CollectorExporterConfigBase` => `OTLPExporterConfigBase` |
| 64 | + - `CollectorExporterError` => `OTLPExporterError` |
| 65 | + - `COLLECTOR_SPAN_KIND_MAPPING` => `OTLP_SPAN_KIND_MAPPING` |
| 66 | + - `collectorTypes` => `otlpTypes` |
| 67 | +- `@opentelemetry/exporter-collector-grpc` => `@opentelemetry/exporter-otlp-grpc` |
| 68 | + - `CollectorTraceExporter` => `OTLPTraceExporter` |
| 69 | + - `CollectorMetricExporter` => `OTLPMetricExporter` |
| 70 | + - `CollectorExporterConfigNode` => `OTLPExporterConfigNode` |
| 71 | +- `@opentelemetry/exporter-collector-proto` => `@opentelemetry/exporter-otlp-proto` |
| 72 | + - `CollectorExporterNodeBase` => `OTLPExporterNodeBase` |
| 73 | + - `CollectorMetricExporter` => `OTLPMetricExporter` |
| 74 | + - `CollectorTraceExporter` => `OTLPTraceExporter` |
| 75 | +- W3C propagators in @opentelemetry/core were renamed |
| 76 | + - `HttpTraceContextPropagator` -> `W3CTraceContextPropagator` |
| 77 | + - `HttpBaggagePropagator` -> `W3CBaggagePropagator` |
| 78 | + |
| 79 | +## 0.24.x to 0.25.x |
| 80 | + |
| 81 | +- SDKs packages for trace and metrics has been renamed to have a consistent naming schema: |
| 82 | + - @opentelemetry/tracing -> @opentelemetry/sdk-trace-base |
| 83 | + - @opentelemetry/node -> @opentelemetry/sdk-trace-node |
| 84 | + - @opentelemetry/web -> @opentelemetry/sdk-trace-web |
| 85 | + - @opentelemetry/metrics -> @opentelemetry/sdk-metrics-base |
| 86 | + - @opentelemetry/node-sdk -> @opentelemetry/sdk-node |
| 87 | + |
| 88 | +## 0.23.x to 0.24.x |
| 89 | + |
| 90 | +- `ResourceAttributes` renamed to `SemanticResourceAttributes` in the `@opentelemetry/semantic-conventions` package |
| 91 | + |
| 92 | +## 0.19.x to 0.20.0 |
| 93 | + |
| 94 | +- `HttpBaggage` renamed to `HttpBaggagePropagator` |
| 95 | + |
| 96 | +- `HttpTraceContext` renamed to `HttpTraceContextPropagator` |
| 97 | + |
| 98 | +- `JaegerHttpTracePropagator` renamed to `JaegerPropagator` |
| 99 | + |
| 100 | +- `serviceName` configuration removed from Collector exporters. Use `service.name` Resource attribute instead. |
| 101 | + |
| 102 | +- Prometheus exporter added suffix `_total` to counter metrics. |
| 103 | + |
| 104 | +## 0.18.x to 0.19.0 |
| 105 | + |
| 106 | +- API is now a peer dependency. This means that users will need to include `@opentelemetry/api` as a dependency of their project in order to use the SDK. NPM version 7+ (Node 15+) should do this automatically. |
| 107 | + |
| 108 | +- All plugins have been removed in favor of instrumentations. |
| 109 | + |
| 110 | +- The `@opentelemetry/propagator-b3` package previously exported three propagators: `B3Propagator`,`B3SinglePropagator`, and `B3MultiPropagator`, but now only exports the `B3Propagator`. It extracts b3 context in single and multi-header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header endcoding during construction: `new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })`. If you were previously using the `B3SinglePropagator` or `B3MultiPropagator` directly, you should update your code to use the `B3Propagator` with the appropriate configuration. See the [readme][otel-propagator-b3] for full details and usage. |
| 111 | + |
| 112 | +- Sampling configuration via environment variable has changed. If you were using `OTEL_SAMPLING_PROBABILITY` then you should replace it with `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=<number>` where `<number>` is a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset. |
| 113 | + |
| 114 | +## 0.17.0 to 0.18.0 |
| 115 | + |
| 116 | +- `diag.setLogLevel` is removed and LogLevel can be set by an optional second parameter to `setLogger` |
| 117 | + |
| 118 | +[PR-1975](https://github.com/open-telemetry/opentelemetry-js/pull/1975) |
| 119 | + |
| 120 | +- Breaking change - The resulting resource MUST have all attributes that are on any of the two input resources. If a key exists on both the old and updating resource, the value of the updating resource MUST be picked - previously it was opposite. |
| 121 | + |
| 122 | +## 0.16.0 to 0.17.0 |
| 123 | + |
| 124 | +[PR-1880](https://github.com/open-telemetry/opentelemetry-js/pull/1880) feat(diag-logger): introduce a new global level api.diag for internal diagnostic logging |
| 125 | + |
| 126 | +[PR-1925](https://github.com/open-telemetry/opentelemetry-js/pull/1925) feat(diag-logger): part 2 - breaking changes - remove api.Logger, api.NoopLogger, core.LogLevel, core.ConsoleLogger |
| 127 | + |
| 128 | +- These PR's remove the previous `Logger` and `LogLevel` implementations and change the way you should use the replacement `DiagLogger` and `DiagLogLevel`, below are simple examples of how to change your existing usages. |
| 129 | + |
| 130 | +### Setting the global diagnostic logger |
| 131 | + |
| 132 | +The new global [`api.diag`](https://github.com/open-telemetry/opentelemetry-js/blob/main/api/src/api/diag.ts) provides the ability to set the global diagnostic logger `setLogger()` and logging level `setLogLevel()`, it is also a `DiagLogger` implementation and should be directly to log diagnostic messages. |
| 133 | + |
| 134 | +All included logger references have been removed in preference to using the global `api.diag` directly, so you no longer need to pass around the logger instance via function parameters or included as part of the configuration for a component. |
| 135 | + |
| 136 | +```javascript |
| 137 | +import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api"; |
| 138 | +// Setting the default Global logger to use the Console |
| 139 | +// And optionally change the logging level (Defaults to INFO) |
| 140 | +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR) |
| 141 | +``` |
| 142 | + |
| 143 | +### Using the logger anywhere in the code |
| 144 | + |
| 145 | +```typescript |
| 146 | +import { diag } from "@opentelemetry/api"; |
| 147 | + |
| 148 | +// Remove or make optional the parameter and don't use it. |
| 149 | +export function MyFunction() { |
| 150 | + diag.debug("..."); |
| 151 | + diag.info("..."); |
| 152 | + diag.warn("..."); |
| 153 | + diag.error("..."); |
| 154 | + diag.verbose(".."); |
| 155 | +} |
| 156 | + |
| 157 | +``` |
| 158 | + |
| 159 | +### Setting the logger back to a noop |
| 160 | + |
| 161 | +```typescript |
| 162 | +import { diag } from "@opentelemetry/api"; |
| 163 | +diag.setLogger(); |
| 164 | + |
| 165 | +``` |
| 166 | + |
| 167 | +[PR-1855](https://github.com/open-telemetry/opentelemetry-js/pull/1855) Use instrumentation loader to load plugins and instrumentations |
| 168 | + |
| 169 | +- Providers do no load the plugins anymore. Also PluginLoader has been removed from providers, use `registerInstrumentations` instead |
| 170 | + |
| 171 | +```javascript |
| 172 | +//Previously in node |
| 173 | +const provider = new NodeTracerProvider({ |
| 174 | + plugins: { |
| 175 | + '@grpc/grpc-js': { |
| 176 | + enabled: true, |
| 177 | + path: '@opentelemetry/plugin-grpc-js', |
| 178 | + }, |
| 179 | + } |
| 180 | +}); |
| 181 | + |
| 182 | +// Now |
| 183 | +const provider = new NodeTracerProvider(); |
| 184 | +const { registerInstrumentations } = require('@opentelemetry/instrumentation'); |
| 185 | +registerInstrumentations({ |
| 186 | + instrumentations: [ |
| 187 | + { |
| 188 | + plugins: { |
| 189 | + '@grpc/grpc-js': { |
| 190 | + enabled: true, |
| 191 | + path: '@opentelemetry/plugin-grpc-js', |
| 192 | + }, |
| 193 | + } |
| 194 | + } |
| 195 | + ], |
| 196 | + tracerProvider: provider, |
| 197 | +}); |
| 198 | + |
| 199 | +// or if you want to load only default instrumentations / plugins |
| 200 | +registerInstrumentations({ |
| 201 | + tracerProvider: provider, |
| 202 | +}); |
| 203 | + |
| 204 | +//Previously in browser |
| 205 | +const provider = new WebTracerProvider({ |
| 206 | + plugins: [ |
| 207 | + new DocumentLoad() |
| 208 | + ] |
| 209 | +}); |
| 210 | +// Now |
| 211 | +const { registerInstrumentations } = require('@opentelemetry/instrumentation'); |
| 212 | +const provider = new WebTracerProvider(); |
| 213 | +registerInstrumentations({ |
| 214 | + instrumentations: [ |
| 215 | + new DocumentLoad(), |
| 216 | + ], |
| 217 | +}); |
| 218 | +``` |
| 219 | + |
| 220 | +- `registerInstrumentations` supports loading old plugins and instrumentations together. It also supports setting tracer provider and meter provider on instrumentations |
| 221 | + |
| 222 | +[PR-1874](https://github.com/open-telemetry/opentelemetry-js/pull/1874) More specific API type names |
| 223 | + |
| 224 | +Some types exported from `"@opentelemetry/api"` have been changed to be more specific. |
| 225 | + |
| 226 | +- `AttributeValue` renamed to `SpanAttributeValue` |
| 227 | +- `Attributes` renamed to `SpanAttributes` |
| 228 | +- `EntryTtl` renamed to `BaggageEntryTtl` |
| 229 | +- `EntryValue` renamed to `BaggageEntryValue` |
| 230 | +- `Status` renamed to `SpanStatus` |
| 231 | +- `StatusCode` renamed to `SpanStatusCode` |
| 232 | + |
| 233 | +## 0.15.0 to 0.16.0 |
| 234 | + |
| 235 | +[PR-1863](https://github.com/open-telemetry/opentelemetry-js/pull/1863) removed public attributes `keepAlive` and `httpAgentOptions` from nodejs `CollectorTraceExporter` and `CollectorMetricExporter` |
| 236 | + |
| 237 | +## 0.14.0 to 0.15.0 |
| 238 | + |
| 239 | +[PR-1764](https://github.com/open-telemetry/opentelemetry-js/pull/1764) removed some APIs from `Tracer`: |
| 240 | + |
| 241 | +- `Tracer.getCurrentSpan()`: use `api.getSpan(api.context.active())` |
| 242 | +- `Tracer.withSpan(span)`: use `api.context.with(api.setSpan(api.context.active(), span))` |
| 243 | +- `Tracer.bind(target)`: use `api.context.bind(target)` |
| 244 | + |
| 245 | +[PR-1797](https://github.com/open-telemetry/opentelemetry-js/pull/1797) chore!: split metrics into its own api package: |
| 246 | + |
| 247 | +- Any references to `require("@opentelemetry/api").metrics` will need to be changed to `require("@opentelemetry/api-metrics").metrics` |
| 248 | + |
| 249 | +[PR-1725](https://github.com/open-telemetry/opentelemetry-js/pull/1725) Use new gRPC default port |
| 250 | + |
| 251 | +- The default port used by `@opentelemetry/exporter-collector-grpc` is changed from `55680` to `4317` |
| 252 | + |
| 253 | +[PR-1749](https://github.com/open-telemetry/opentelemetry-js/pull/1749) chore: improve naming of span related context APIs |
| 254 | + |
| 255 | +- Rename `[gs]etActiveSpan()` to `[gs]etSpan()` |
| 256 | +- Rename `setExtractedSpanContext()` to `setSpanContext()` |
| 257 | +- Rename `getParentSpanContext()` to `getSpanContext()` |
0 commit comments