Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: shorten readme sections #4460

Merged
merged 5 commits into from
Feb 6, 2024
Merged

docs: shorten readme sections #4460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
84f9af6
docs: shorten readme sections
legendecas Feb 5, 2024
9d01a01
Merge branch 'main' into doc/shorten
pichlermarc Feb 5, 2024
ff4b021
Merge branch 'main' into doc/shorten
pichlermarc Feb 6, 2024
7009d6b
Merge branch 'main' into doc/shorten
pichlermarc Feb 6, 2024
c8019db
Merge branch 'main' into doc/shorten
pichlermarc Feb 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ For experimental package changes, see the [experimental CHANGELOG](experimental/

### :books: (Refine Doc)

* docs: shorten readme sections [#4460](https://github.com/open-telemetry/opentelemetry-js/pull/4460) @legendecas

### :house: (Internal)

## 1.21.0
Expand Down
304 changes: 28 additions & 276 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,24 +149,33 @@ The below table describes which versions of each set of packages are expected to
| 1.19.x | 0.46.x |
| 1.18.x | 0.45.x |
| 1.17.x | 0.44.x |
| 1.16.x | 0.42.x |
| 1.15.x | 0.41.x |
| 1.14.x | 0.40.x |
| 1.13.x | 0.39.x |
| 1.12.x | 0.38.x |
| 1.11.x | 0.37.x |
| 1.10.x | 0.36.x |
| 1.9.x | 0.35.x |
| 1.8.x (this and later versions require API >=1.3.0 for metrics) | 0.34.x |
| 1.7.x | 0.33.x |
| 1.6.x | 0.32.x |
| 1.5.x | 0.31.x |
| 1.4.x | 0.30.x |
| 1.3.x | 0.29.x |
| 1.2.x | 0.29.x |
| 1.1.x | 0.28.x |
| 1.0.x | 0.27.x |
| 1.0.x (this and later versions require API >=1.0.0 for traces) | 0.26.x |

<details>
<summary>Older version compatibility matrix</summary>

<table>
<tr><th>Stable Packages</th> <th>Experimental Packages</th></tr>
<tr><td>1.16.x</td> <td>0.42.x</td></tr>
<tr><td>1.15.x</td> <td>0.41.x</td></tr>
<tr><td>1.14.x</td> <td>0.40.x</td></tr>
<tr><td>1.13.x</td> <td>0.39.x</td></tr>
<tr><td>1.12.x</td> <td>0.38.x</td></tr>
<tr><td>1.11.x</td> <td>0.37.x</td></tr>
<tr><td>1.10.x</td> <td>0.36.x</td></tr>
<tr><td>1.9.x</td> <td>0.35.x</td></tr>
<tr><td>1.8.x (this and later versions require API >=1.3.0 for metrics)</td><td>0.34.x</td></tr>
<tr><td>1.7.x</td> <td>0.33.x</td></tr>
<tr><td>1.6.x</td> <td>0.32.x</td></tr>
<tr><td>1.5.x</td> <td>0.31.x</td></tr>
<tr><td>1.4.x</td> <td>0.30.x</td></tr>
<tr><td>1.3.x</td> <td>0.29.x</td></tr>
<tr><td>1.2.x</td> <td>0.29.x</td></tr>
<tr><td>1.1.x</td> <td>0.28.x</td></tr>
<tr><td>1.0.x</td> <td>0.27.x</td></tr>
<tr><td>1.0.x (this and later versions require API >=1.0.0 for traces)</td><td>0.26.x</td></tr>
</table>

</details>

## Versioning

Expand Down Expand Up @@ -299,266 +308,9 @@ These instrumentations are hosted at <https://github.com/open-telemetry/opentele
| -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [@opentelemetry/shim-opentracing][otel-shim-opentracing] | OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry |

## Upgrade guidelines

### 0.37.x to 0.38.0

- `@opentelemetry/sdk-node` `NodeSDKConfiguration.defaultAttributes` has been unused and was removed as the concept does not exist in OpenTelemetry anymore
- Please use `NodeSDKConfiguration.resource` instead.

### 0.35.x to 0.36.0

- `@opentelemetry/sdk-node` changed `await start()` to now be synchronous
- `@opentelemetry/sdk-node` changed `await detectResources()` to now be synchronous

### 0.28.x to 0.29.x

- `@opentelemetry/exporter-trace-otlp-http` is now exporting `scopeSpans` instead of `instrumentationLibrarySpans`
- this exporter now requires collector version `0.48` and up.
- `@opentelemetry/exporter-metrics-otlp-http` is now exporting `scopeMetrics` instead of `instrumentationLibraryMetrics`
- this exporter now requires collector version `0.48` and up.

### 0.27.x to 0.28.x

- In `@opentelemetry/exporter-trace-otlp-http`, `OTLPExporterBase._isShutdown` is replaced with `_shutdownOnce`.

### 0.26.x to 0.27.x

Metric and trace exporters are split into separate packages:

- `@opentelemetry/exporter-otlp-http` => `@opentelemetry/exporter-trace-otlp-http` and `@opentelemetry/exporter-metrics-otlp-http`
- `@opentelemetry/exporter-otlp-grpc` => `@opentelemetry/exporter-trace-otlp-grpc` and `@opentelemetry/exporter-metrics-otlp-grpc`
- `@opentelemetry/exporter-otlp-proto` => `@opentelemetry/exporter-trace-otlp-proto` and `@opentelemetry/exporter-metrics-otlp-proto`

Metric types are renamed:

- `@openetelemetry/api-metrics`
- `Meter`
- `createValueRecorder` => `createHistogram`
- `createValueObserver` => `createObservableGauge`
- `createSumObserver` => `createObservableCounter`
- `createUpDownSumObserver` => `createObservableUpDownCounter`
- `ValueRecorder` => `Histogram`
- `ValueObserver` => `ObservableGauge`
- `SumObserver` => `ObservableCounter`
- `UpDownSumObserver` => `ObservableUpDownCounter`
- `ObserverResult` => `ObservableResult`
- `Observation.observer` => `Observation.observable`
- `@opentelemetry/sdk-metrics-base`
- `MetricKind`
- `VALUE_RECORDER` => `HISTOGRAM`
- `SUM_OBSERVER` => `OBSERVABLE_COUNTER`
- `UP_DOWN_SUM_OBSERVER` => `OBSERVABLE_UP_DOWN_COUNTER`
- `VALUE_OBSERVER` => `OBSERVABLE_GAUGE`

### 0.25.x to 1.x.y

Collector exporter packages and types are renamed:

- `@opentelemetry/exporter-collector` => `@opentelemetry/exporter-otlp-http`
- `CollectorExporterBase` => `OTLPExporterBase`
- `CollectorTraceExporter` => `OTLPTraceExporter`
- `CollectorMetricExporter` => `OTLPMetricExporter`
- `CollectorExporterBrowserBase` => `OTLPExporterBrowserBase`
- `CollectorExporterNodeBase` => `OTLPExporterNodeBase`
- `CollectorExporterConfigBase` => `OTLPExporterConfigBase`
- `CollectorExporterError` => `OTLPExporterError`
- `COLLECTOR_SPAN_KIND_MAPPING` => `OTLP_SPAN_KIND_MAPPING`
- `collectorTypes` => `otlpTypes`
- `@opentelemetry/exporter-collector-grpc` => `@opentelemetry/exporter-otlp-grpc`
- `CollectorTraceExporter` => `OTLPTraceExporter`
- `CollectorMetricExporter` => `OTLPMetricExporter`
- `CollectorExporterConfigNode` => `OTLPExporterConfigNode`
- `@opentelemetry/exporter-collector-proto` => `@opentelemetry/exporter-otlp-proto`
- `CollectorExporterNodeBase` => `OTLPExporterNodeBase`
- `CollectorMetricExporter` => `OTLPMetricExporter`
- `CollectorTraceExporter` => `OTLPTraceExporter`
- W3C propagators in @opentelemetry/core were renamed
- `HttpTraceContextPropagator` -> `W3CTraceContextPropagator`
- `HttpBaggagePropagator` -> `W3CBaggagePropagator`

### 0.24.x to 0.25.x

- SDKs packages for trace and metrics has been renamed to have a consistent naming schema:
- @opentelemetry/tracing -> @opentelemetry/sdk-trace-base
- @opentelemetry/node -> @opentelemetry/sdk-trace-node
- @opentelemetry/web -> @opentelemetry/sdk-trace-web
- @opentelemetry/metrics -> @opentelemetry/sdk-metrics-base
- @opentelemetry/node-sdk -> @opentelemetry/sdk-node

### 0.23.x to 0.24.x

- `ResourceAttributes` renamed to `SemanticResourceAttributes` in the `@opentelemetry/semantic-conventions` package

### 0.19.x to 0.20.0

- `HttpBaggage` renamed to `HttpBaggagePropagator`

- `HttpTraceContext` renamed to `HttpTraceContextPropagator`

- `JaegerHttpTracePropagator` renamed to `JaegerPropagator`

- `serviceName` configuration removed from Collector exporters. Use `service.name` Resource attribute instead.

- Prometheus exporter added suffix `_total` to counter metrics.

### 0.18.x to 0.19.0

- 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.

- All plugins have been removed in favor of instrumentations.

- 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.

- 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.

### 0.17.0 to 0.18.0

- `diag.setLogLevel` is removed and LogLevel can be set by an optional second parameter to `setLogger`

[PR-1975](https://github.com/open-telemetry/opentelemetry-js/pull/1975)

- 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.

### 0.16.0 to 0.17.0

[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

[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

- 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.

#### Setting the global diagnostic logger

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.

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.

```javascript
import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
// Setting the default Global logger to use the Console
// And optionally change the logging level (Defaults to INFO)
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR)
```

#### Using the logger anywhere in the code

```typescript
import { diag } from "@opentelemetry/api";

// Remove or make optional the parameter and don't use it.
export function MyFunction() {
diag.debug("...");
diag.info("...");
diag.warn("...");
diag.error("...");
diag.verbose("..");
}

```

#### Setting the logger back to a noop

```typescript
import { diag } from "@opentelemetry/api";
diag.setLogger();

```

[PR-1855](https://github.com/open-telemetry/opentelemetry-js/pull/1855) Use instrumentation loader to load plugins and instrumentations

- Providers do no load the plugins anymore. Also PluginLoader has been removed from providers, use `registerInstrumentations` instead

```javascript
//Previously in node
const provider = new NodeTracerProvider({
plugins: {
'@grpc/grpc-js': {
enabled: true,
path: '@opentelemetry/plugin-grpc-js',
},
}
});

// Now
const provider = new NodeTracerProvider();
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
registerInstrumentations({
instrumentations: [
{
plugins: {
'@grpc/grpc-js': {
enabled: true,
path: '@opentelemetry/plugin-grpc-js',
},
}
}
],
tracerProvider: provider,
});

// or if you want to load only default instrumentations / plugins
registerInstrumentations({
tracerProvider: provider,
});

//Previously in browser
const provider = new WebTracerProvider({
plugins: [
new DocumentLoad()
]
});
// Now
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const provider = new WebTracerProvider();
registerInstrumentations({
instrumentations: [
new DocumentLoad(),
],
});
```

- `registerInstrumentations` supports loading old plugins and instrumentations together. It also supports setting tracer provider and meter provider on instrumentations

[PR-1874](https://github.com/open-telemetry/opentelemetry-js/pull/1874) More specific API type names

Some types exported from `"@opentelemetry/api"` have been changed to be more specific.

- `AttributeValue` renamed to `SpanAttributeValue`
- `Attributes` renamed to `SpanAttributes`
- `EntryTtl` renamed to `BaggageEntryTtl`
- `EntryValue` renamed to `BaggageEntryValue`
- `Status` renamed to `SpanStatus`
- `StatusCode` renamed to `SpanStatusCode`

### 0.15.0 to 0.16.0

[PR-1863](https://github.com/open-telemetry/opentelemetry-js/pull/1863) removed public attributes `keepAlive` and `httpAgentOptions` from nodejs `CollectorTraceExporter` and `CollectorMetricExporter`

### 0.14.0 to 0.15.0

[PR-1764](https://github.com/open-telemetry/opentelemetry-js/pull/1764) removed some APIs from `Tracer`:

- `Tracer.getCurrentSpan()`: use `api.getSpan(api.context.active())`
- `Tracer.withSpan(span)`: use `api.context.with(api.setSpan(api.context.active(), span))`
- `Tracer.bind(target)`: use `api.context.bind(target)`

[PR-1797](https://github.com/open-telemetry/opentelemetry-js/pull/1797) chore!: split metrics into its own api package:

- Any references to `require("@opentelemetry/api").metrics` will need to be changed to `require("@opentelemetry/api-metrics").metrics`

[PR-1725](https://github.com/open-telemetry/opentelemetry-js/pull/1725) Use new gRPC default port

- The default port used by `@opentelemetry/exporter-collector-grpc` is changed from `55680` to `4317`

[PR-1749](https://github.com/open-telemetry/opentelemetry-js/pull/1749) chore: improve naming of span related context APIs

- Rename `[gs]etActiveSpan()` to `[gs]etSpan()`
- Rename `setExtractedSpanContext()` to `setSpanContext()`
- Rename `getParentSpanContext()` to `getSpanContext()`

## Useful links

- Upgrade guidelines: [Upgrade Guide](./doc/upgrade-guide.md)
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]

Expand Down
0 maintenance/bug_triage.md → doc/contributing/bug_triage.md
View file
Open in desktop
File renamed without changes.
12 changes: 4 additions & 8 deletions doc/GUIDELINES.md → doc/contributing/dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
# OpenTelemetry JS Code Contribution Guide

This document outlines the essential guidelines for contributing code to the OpenTelemetry JS repository. These guidelines are designed to ensure consistency, stability, and the highest quality of code across the project.

## Dependencies
# OpenTelemetry Dependencies

This section refers to `"dependencies"` and `"devDependencies"` entries in `package.json` file.
> [!IMPORTANT]
> Not all libraries follow [Semantic Versioning](https://semver.org/). Even those who do might occasionally introduce breaking changes due to human errors. Exceptions to the guidelines in this document MAY be granted by Approvers or Maintainers to work around this.

### Development Dependencies
## Development Dependencies

`"devDependencies"` SHOULD be pinned to reduce the risk of autobreaking the build. Since we cannot use the `package-lock.json` file (because the libraries are distributed without it), control over the version our contributors will get is limited. By using pinned versions, we prevent potential disruptions caused by unpinned versions.

Expand All @@ -17,15 +13,15 @@ This section refers to `"dependencies"` and `"devDependencies"` entries in `pack
> [!NOTE]
> As this approach might leave our project with outdated tooling, we adopt `renovate-bot`. This automated dependency update tool proactively opens pull requests upon the release of new patch/minor/major versions. The complete configuration for renovate-bot can be found in [renovate.json](../renovate.json) file.

### @opentelemetry/* dependencies
## @opentelemetry/* dependencies

All packages from the `@opentelemetry/` namespace MUST have the same pinned version, as these dependencies are automatically updated on each release by lerna.

**Example:** all packages under `packages/` should consistently maintain the same version, as should those under `experimental/packages/`.

An exception is granted for dependencies on `@opentelemetry/api`, which, if used by the package SHOULD NOT be included as a `dependency`. `@opentelemetry/api` SHOULD be included as a `peerDependency` instead. The version range of the `peerDependency` SHOULD reflect the minimum supported, and SHOULD NOT allow versions greater than the latest released minor version.

### Third-Party Library Dependencies
## Third-Party Library Dependencies

Packages categorized as third-party and listed under the `"dependencies"` section (e.g., @grpc/grpc-js, @grpc/proto-loader, shimmer, etc.) should remain unpinned and utilize the caret (`^`) symbol. This approach offers several advantages:

Expand Down
0 maintenance/npm_workspaces.md → doc/contributing/npm_workspaces.md
View file
Open in desktop
File renamed without changes.
0 maintenance/releasing.md → doc/contributing/releasing.md
View file
Open in desktop
File renamed without changes.
Loading
Loading