From 9721b88ad3d9211b6e93dcbaa174e784ab1b87b2 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Thu, 9 Mar 2023 07:37:38 -0800 Subject: [PATCH 01/25] Add head sampling section + elaborate tail sampling (#2463) Co-authored-by: Kent Quirk --- content/en/docs/concepts/sampling/index.md | 98 +++++++++++++++++++--- 1 file changed, 87 insertions(+), 11 deletions(-) diff --git a/content/en/docs/concepts/sampling/index.md b/content/en/docs/concepts/sampling/index.md index db6fe2e397bd..b74d602e83d6 100644 --- a/content/en/docs/concepts/sampling/index.md +++ b/content/en/docs/concepts/sampling/index.md @@ -30,18 +30,94 @@ want to sample. You might want to customize your sampling strategy to: to see traces with specific user attributes. - **Filter out noise**: For example, you may want to filter out health checks. -## What is tail-based sampling? +## Terminology -Tail-based sampling is where the decision to sample a trace happens _after_ all -the spans in a request have been completed. This is in contrast to head-based -sampling, where the decision is made at the _beginning_ of a request when the -root span begins processing. Tail-based sampling gives you the option to filter -your traces based on specific criteria, which isn’t an option with head-based -sampling. +It's important to use consistent terminology when discussing sampling. A trace +or span is considered "sampled" or "not sampled": + +- **Sampled**: A trace or span is processed and exported. Because it is chosen + by the sampler as a representive of the population, it is considered + "sampled". +- **Not sampled**: A trace or span is not processed or exported. Because it is + not chosen by the sampler, it is considered "not sampled". + +Sometimes, the definitions of these terms get mixed up. You may find someone +state that they are "sampling out data" or that data not processed or exported +is considered "sampled". These are incorrect statements. + +## Head Sampling + +Head sampling is a sampling technique used to make a sampling decision as early +as possible. A decision to sample or drop a span or trace is not made by +inspecting the trace as a whole. + +For example, the most common form of head sampling is +[Consistent Probability Sampling](/docs/reference/specification/trace/tracestate-probability-sampling/#consistent-probability-sampling). +It may also be referred to as Deterministic Sampling. In this case, a sampling +decision is made based on the trace ID and a desired percentage of traces to +sample. This ensures that whole traces are sampled - no missing spans - at a +consistent rate, such as 5% of all traces. + +The upsides to head sampling are: + +- Easy to understand +- Easy to configure +- Efficient +- Can be done at any point in the trace collection pipeline + +The primary downside to head sampling is that it is not possible make a sampling +decision based on data in the entire trace. This means that head sampling is +effective as a blunt instrument, but is wholly insufficient for sampling +strategies that must take whole-system information into account. For example, it +is not possible to use head sampling to ensure that all traces with an error +within them are sampled. For this, you need Tail Sampling. + +## Tail Sampling + +Tail sampling is where the decision to sample a trace takes place by considering +all or most of the spans within the trace. Tail Sampling gives you the option to +sample your traces based on specific criteria derived from different parts of a +trace, which isn’t an option with Head Sampling. ![Illustration shows how spans originate from a root span. After the spans are complete, the tail sampling processor makes a sampling decision.](tail_sampling_process.png) -Tail sampling lets you see only the traces that are of interest to you. You also -lower data ingest and storage costs because you’re only exporting a -predetermined subset of your traces. For instance, as an app developer, I may -only be interested in traces with errors or latency for debugging. +Some examples of how you can use Tail Sampling include: + +- Always sampling traces that contain an error +- Sampling traces based on overall latency +- Sampling traces based on the presence or value of specific attributes on one + or more spans in a trace; for example, sampling more traces originating from a + newly deployed service +- Applying different sampling rates to traces based on certain criteria + +As you can see, tail sampling allows for a much higher degree of sophistication. +For larger systems that must sample telemetry, it is almost always necessary to +use Tail Sampling to balance data volume with usefulness of that data. + +There are three primary downsides to tail sampling today: + +- Tail sampling can be difficult to implement. Depending on the kind of sampling + techniques available to you, it is not always a "set and forget" kind of + thing. As your systems change, so too will your sampling strategies. For a + large and sophisticated distributed system, rules that implement sampling + strategies can also be large and sophisticated. +- Tail sampling can be difficult to operate. The component(s) that implement + tail sampling must be stateful systems that can accept and store a large + amount of data. Depending on traffic patterns, this can require dozens or even + hundreds of nodes that all utilize resources differently. Furthermore, a tail + sampler may need to "fall back" to less computationally-intensive sampling + techniques if it is unable to keep up with the volume of data it is receiving. + Because of these factors, it is critical to monitor tail sampling components + to ensure that they have the resources they need to make the correct sampling + decisions. +- Tail samplers often end up being in the domain of vendor-specific technology + today. If you're using a paid vendor for Observability, the most effective + tail sampling options available to you may be limited to what the vendor + offers. + +Finally, for some systems, tail sampling may be used in conjunction with Head +Sampling. For example, a set of services that produce an extremely high volume +of trace data may first use head sampling to only sample a small percentage of +traces, and then later in the telemetry pipeline use tail sampling to make more +sophisticated sampling decisions before exporting to a backend. This is often +done in the interest of protecting the telemetry pipeline from being overloaded. From 89e594c8c743d6829360f41182a5dc2dfe9d542f Mon Sep 17 00:00:00 2001 From: Ron Yishai Date: Thu, 9 Mar 2023 17:46:28 +0200 Subject: [PATCH 02/25] Update Python agent-config (#2272) Co-authored-by: Phillip Carter --- .../python/automatic/agent-config.md | 44 ++++++------------- 1 file changed, 13 insertions(+), 31 deletions(-) diff --git a/content/en/docs/instrumentation/python/automatic/agent-config.md b/content/en/docs/instrumentation/python/automatic/agent-config.md index 42d89569a6b9..6241d2d70c2f 100644 --- a/content/en/docs/instrumentation/python/automatic/agent-config.md +++ b/content/en/docs/instrumentation/python/automatic/agent-config.md @@ -28,49 +28,31 @@ opentelemetry-instrument \ Here's an explanation of what each configuration does: -- `traces_exporter` specifies which trace exporter to use. In this case, traces - are being exported to `console` (stdout) and to `otlp`. The `otlp` option - tells `opentelemetry-instrument` to send it to an endpoint that accepts OTLP - via gRPC. The full list of available options for traces_exporter can be found +- `traces_exporter` specifies which traces exporter to use. In this case, traces + are being exported to `console` (stdout) and with `otlp`. The `otlp` option + tells `opentelemetry-instrument` to send the traces to an endpoint that + accepts OTLP via gRPC. In order to use HTTP instead of gRPC, add + `--exporter_otlp_protocol http`. The full list of available options for + traces_exporter can be found [here](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation). -- `otlp` used above for `traces_exporter` is the equivalent of using - `otlp_proto_grpc`. To send traces via HTTP instead of gRPC, replace - `otlp_proto_grpc` (or `otlp`) with `otlp_proto_http`. - `metrics_exporter` specifies which metrics exporter to use. In this case, metrics are being exported to `console` (stdout). It is currently required for your to specify a metrics exporter. If you aren't exporting metrics, specify `none` as the value instead. -- `service_name` sets the name of the service associated to the trace, and is - sent to your [Observability back-end](/ecosystem/vendors/). -- `exporter_otlp_endpoint` tells `opentelemetry-instrument` to send the traces - to the given [Observability back-end's](/ecosystem/vendors/) endpiont via - gRPC, or directly to the [OpenTelemetry Collector](/docs/collector/). +- `service_name` sets the name of the service associated with your telemetry, + and is sent to your [Observability backend](/ecosystem/vendors/). +- `exporter_otlp_endpoint` sets the endpoint where telemetry is exported to. If + omitted, the default [Collector](/docs/collector) endpoint will be used, which + is `0.0.0.0:4317` for gRPC and `0.0.0.0:4318` for HTTP. - `exporter_otlp_headers` is required depending on your chosen Observability - back-end. More info exporter OTLP headers be found + backend. More info exporter OTLP headers be found [here](/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers). -- If `exporter_otlp_endpoint` is omitted, the agent assumes that you are using - the default Collector gRPC endpoint, `0.0.0.0:4317`. The above command is the - equivalent of saying: - - ```console - opentelemetry-instrument \ - --traces_exporter console,otlp_proto_grpc \ - --metrics_exporter console\ - --service_name your-service-name \ - --exporter_otlp_endpoint 0.0.0.0:4317 \ - --exporter_otlp_insecure true \ - python myapp.py - ``` - - For HTTP, replace `otlp_proto_grpc` with `otlp_proto_http`. If left - unspecified, the endpoint is now assumed to be `0.0.0.0:4318` (default - Collector HTTP endpoint). ### Environment Variables In some cases, configuring via [Environment Variables](/docs/concepts/sdk-configuration/) is more preferred. -Any setting configurable with a configuration property can also be configured +Any setting configurable with a command-line argument can also be configured with an Environment Variable. You can apply the following steps to determine the correct name mapping of the From 05515c59036bd1bae93f85bf199537d23acea552 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 9 Mar 2023 19:32:46 -0500 Subject: [PATCH 03/25] Link to local spec pages (#2476) --- content/en/blog/2022/debug-otel-with-otel/index.md | 2 +- content/en/blog/2022/instrument-kafka-clients/index.md | 2 +- content/en/blog/2023/http-conventions-stability.md | 5 ++--- content/en/docs/collector/transforming-telemetry.md | 2 +- content/en/docs/demo/services/frontend.md | 2 +- content/en/docs/demo/services/load-generator.md | 2 +- content/en/docs/instrumentation/python/automatic/example.md | 2 +- 7 files changed, 8 insertions(+), 9 deletions(-) diff --git a/content/en/blog/2022/debug-otel-with-otel/index.md b/content/en/blog/2022/debug-otel-with-otel/index.md index 3e1b667ff4b8..2ea13c6fb2c9 100644 --- a/content/en/blog/2022/debug-otel-with-otel/index.md +++ b/content/en/blog/2022/debug-otel-with-otel/index.md @@ -250,7 +250,7 @@ COPY opentelemetry_module.conf /etc/nginx/conf.d /blog/2022/instrument-nginx/#put-nginx-between-two-services [localhost:16686]: http://localhost:16686/ [http request & response headers]: - https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers + /docs/reference/specification/trace/semantic_conventions/http/#http-request-and-response-headers [rfc7230]: https://httpwg.org/specs/rfc7230.html#field.order [added some checks to the nginx module]: https://github.com/open-telemetry/opentelemetry-cpp-contrib/pull/204 diff --git a/content/en/blog/2022/instrument-kafka-clients/index.md b/content/en/blog/2022/instrument-kafka-clients/index.md index e87972d69ebb..69da4715319d 100644 --- a/content/en/blog/2022/instrument-kafka-clients/index.md +++ b/content/en/blog/2022/instrument-kafka-clients/index.md @@ -23,7 +23,7 @@ comes into the picture. It provides multiple instrumentation libraries for adding tracing to messaging based applications. Of course, there is one for Apache Kafka clients. It also defines the specification of semantic conventions for -[messaging systems](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md). +[messaging systems](/docs/reference/specification/trace/semantic_conventions/messaging/). But usually, the architecture can even be more complicated: having applications not able to connect directly to the Apache Kafka cluster and talking its own diff --git a/content/en/blog/2023/http-conventions-stability.md b/content/en/blog/2023/http-conventions-stability.md index 593525312c4a..8db256e88325 100644 --- a/content/en/blog/2023/http-conventions-stability.md +++ b/content/en/blog/2023/http-conventions-stability.md @@ -6,9 +6,8 @@ author: '[Trask Stalnaker](https://github.com/trask) (Microsoft)' --- The OpenTelemetry community is beginning the final push to declare HTTP -[tracing](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md) -and -[metrics](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/http-metrics.md) +[tracing](/docs/reference/specification/trace/semantic_conventions/http/) and +[metrics](/docs/reference/specification/metrics/semantic_conventions/http-metrics/) semantic conventions stable! Following the recently proposed diff --git a/content/en/docs/collector/transforming-telemetry.md b/content/en/docs/collector/transforming-telemetry.md index dbf1f612476a..c41e9250e503 100644 --- a/content/en/docs/collector/transforming-telemetry.md +++ b/content/en/docs/collector/transforming-telemetry.md @@ -80,7 +80,7 @@ processors: ``` The resource processor has an identical configuration, but applies only to -[resource attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md). +[resource attributes](/docs/reference/specification/resource/semantic_conventions/). Use the resource processor to modify infrastructure metadata related to telemetry. For example, this inserts the Kubernetes cluster name: diff --git a/content/en/docs/demo/services/frontend.md b/content/en/docs/demo/services/frontend.md index 85359a978806..0fa27dd2a77c 100644 --- a/content/en/docs/demo/services/frontend.md +++ b/content/en/docs/demo/services/frontend.md @@ -17,7 +17,7 @@ libraries to leverage, or make use of the `getNodeAutoInstrumentations()` function which includes most popular frameworks. The `utils/telemetry/Instrumentation.js` file contains all code required to initialize the SDK and auto-instrumentation based on standard -[OpenTelemetry environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md) +[OpenTelemetry environment variables](/docs/reference/specification/sdk-environment-variables/) for OTLP export, resource attributes, and service name. ```javascript diff --git a/content/en/docs/demo/services/load-generator.md b/content/en/docs/demo/services/load-generator.md index 237fac8584e5..9a96ee264ece 100644 --- a/content/en/docs/demo/services/load-generator.md +++ b/content/en/docs/demo/services/load-generator.md @@ -18,7 +18,7 @@ Since this service is a OpenTelemetry SDK is initialized after the import statements. This code will create a tracer provider, and establish a Span Processor to use. Export endpoints, resource attributes, and service name are automatically set using -[OpenTelemetry environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md). +[OpenTelemetry environment variables](/docs/reference/specification/sdk-environment-variables/). ```python tracer_provider = TracerProvider() diff --git a/content/en/docs/instrumentation/python/automatic/example.md b/content/en/docs/instrumentation/python/automatic/example.md index 76c7675350b3..475a67f772df 100644 --- a/content/en/docs/instrumentation/python/automatic/example.md +++ b/content/en/docs/instrumentation/python/automatic/example.md @@ -347,7 +347,7 @@ If those headers are available, they will be included in your span: ``` [semantic convention]: - https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers + /docs/reference/specification/trace/semantic_conventions/http/#http-request-and-response-headers [api reference]: https://opentelemetry-python.readthedocs.io/en/latest/index.html [distro]: From 9f825ae2a7ec6a6a8291665510b8d84f2a017cdf Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 9 Mar 2023 19:48:36 -0500 Subject: [PATCH 04/25] Python agent config headings clean up (#2475) Co-authored-by: Phillip Carter --- .../python/automatic/agent-config.md | 30 +++++++++---------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/content/en/docs/instrumentation/python/automatic/agent-config.md b/content/en/docs/instrumentation/python/automatic/agent-config.md index 6241d2d70c2f..0f4a453b5c85 100644 --- a/content/en/docs/instrumentation/python/automatic/agent-config.md +++ b/content/en/docs/instrumentation/python/automatic/agent-config.md @@ -2,22 +2,20 @@ title: Agent Configuration linkTitle: Configuration weight: 45 -spelling: cSpell:ignore distro mkdir uninstrumented virtualenv +spelling: cSpell:ignore distro mkdir myapp uninstrumented virtualenv --- -## Configuring the agent - The agent is highly configurable, either by: -- Passing it configuration properties from the CLI +- Passing configuration properties from the CLI - Setting - [environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md) + [environment variables](/docs/reference/specification/sdk-environment-variables/) -### Configuration properties +## Configuration properties Here's an example of agent configuration via configuration properties: -```console +```sh opentelemetry-instrument \ --traces_exporter console,otlp \ --metrics_exporter console \ @@ -33,8 +31,8 @@ Here's an explanation of what each configuration does: tells `opentelemetry-instrument` to send the traces to an endpoint that accepts OTLP via gRPC. In order to use HTTP instead of gRPC, add `--exporter_otlp_protocol http`. The full list of available options for - traces_exporter can be found - [here](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation). + traces_exporter, see the Python contrib + [OpenTelemetry Instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation). - `metrics_exporter` specifies which metrics exporter to use. In this case, metrics are being exported to `console` (stdout). It is currently required for your to specify a metrics exporter. If you aren't exporting metrics, specify @@ -42,16 +40,16 @@ Here's an explanation of what each configuration does: - `service_name` sets the name of the service associated with your telemetry, and is sent to your [Observability backend](/ecosystem/vendors/). - `exporter_otlp_endpoint` sets the endpoint where telemetry is exported to. If - omitted, the default [Collector](/docs/collector) endpoint will be used, which - is `0.0.0.0:4317` for gRPC and `0.0.0.0:4318` for HTTP. + omitted, the default [Collector](/docs/collector/) endpoint will be used, + which is `0.0.0.0:4317` for gRPC and `0.0.0.0:4318` for HTTP. - `exporter_otlp_headers` is required depending on your chosen Observability backend. More info exporter OTLP headers be found [here](/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers). -### Environment Variables +## Environment Variables In some cases, configuring via -[Environment Variables](/docs/concepts/sdk-configuration/) is more preferred. +[environment variables](/docs/concepts/sdk-configuration/) is more preferred. Any setting configurable with a command-line argument can also be configured with an Environment Variable. @@ -64,11 +62,11 @@ desired configuration property: For example, `exporter_otlp_endpoint` would convert to `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`. -### Disabling Specific Instrumentations +## Disabling Specific Instrumentations The Python agent by default will detect a python program's packages and -instrument any packages it can. -This makes instrumentation easy, but can result in too much or unwanted data. +instrument any packages it can. This makes instrumentation easy, but can result +in too much or unwanted data. You can omit specific packages from instrumentation by using the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` environment variable. The environment From 675a252e4b14b6b3354e1618ed66f6b89da67e0f Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Fri, 10 Mar 2023 07:04:51 -0800 Subject: [PATCH 05/25] Cleanup + correct node getting started (#2470) Co-authored-by: Patrice Chalin --- .../js/getting-started/nodejs.md | 91 +++++++++---------- 1 file changed, 41 insertions(+), 50 deletions(-) diff --git a/content/en/docs/instrumentation/js/getting-started/nodejs.md b/content/en/docs/instrumentation/js/getting-started/nodejs.md index 824bea5a79d1..24d0c79aaa1e 100644 --- a/content/en/docs/instrumentation/js/getting-started/nodejs.md +++ b/content/en/docs/instrumentation/js/getting-started/nodejs.md @@ -16,23 +16,27 @@ Ensure that you have the following installed locally: ## Example Application -This is a small example application we will monitor in this guide. +The following example uses a basic Express application. ### Dependencies -Create an empty package.json: +First, create an empty package.json: ```shell npm init -f ``` -Install dependencies used by the example. +Next, install Express dependencies. {{< tabpane lang=shell persistLang=false >}} {{< tab TypeScript >}} -npm install express typescript ts-node @types/express @types/node +npm install typescript \ + ts-node \ + @types/node \ + express \ + @types/express \ {{< /tab >}} {{< tab JavaScript >}} @@ -111,47 +115,32 @@ Listening for requests on http://localhost:8080 ## Tracing +The following shows how to install, initialize, and run an application +instrumented with traces. + ### Dependencies -The following dependencies are required to trace a Node.js application. +First, install the Node SDK and autoinstrumentations package. -#### Core Dependencies +The Node SDK lets you intialize OpenTelemetry with several configuration +defaults that are correct for the majorty of use cases. -These dependencies are required to configure the tracing SDK and create spans. +The `auto-instrumentations-node` package installs instrumentation packages that +will automatically create spans corresponding to code called in libraries. In +this case, it provides instrumentation for Express, letting the example app +automatically create spans for each incoming request. ```shell -npm install @opentelemetry/sdk-node @opentelemetry/api +npm install @opentelemetry/sdk-node \ + @opentelemetry/auto-instrumentations-node ``` -#### Exporter - -In the following example, we will use the `ConsoleSpanExporter` which prints all -spans to the console. - -In order to visualize and analyze your traces, you will need to export them to a -tracing backend. Follow [these instructions](../../exporters) for setting up a -backend and exporter. - -You may also want to use the `BatchSpanProcessor` to export spans in batches in -order to more efficiently use resources. - -#### Instrumentation Modules - -Many common modules such as the `http` standard library module, `express`, and -others can be automatically instrumented using autoinstrumentation modules. To -find autoinstrumentation modules, you can look at the +To find all autoinstrumentation modules, you can look at the [registry](/ecosystem/registry/?language=js&component=instrumentation). -You can also install all instrumentations maintained by the OpenTelemetry -authors by using the `@opentelemetry/auto-instrumentations-node` module. - -```shell -npm install @opentelemetry/auto-instrumentations-node -``` - ### Setup -The tracing setup and configuration should be run before your application code. +The tracing setup and configuration must be run _before_ your application code. One tool commonly used for this task is the [`-r, --require module`](https://nodejs.org/api/cli.html#cli_r_require_module) flag. @@ -163,20 +152,21 @@ Create a file named `tracing.ts|js`, which will contain your tracing setup code. {{< tab TypeScript >}} /*tracing.ts*/ -// Require dependencies -import * as opentelemetry from "@opentelemetry/sdk-node"; -import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"; -import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +import { NodeSDK } from '@opentelemetry/sdk-node'; +import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'; +import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; -// For troubleshooting, set the log level to DiagLogLevel.DEBUG -diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO); - -const sdk = new opentelemetry.NodeSDK({ - traceExporter: new opentelemetry.tracing.ConsoleSpanExporter(), +const sdk = new NodeSDK({ + traceExporter: new ConsoleSpanExporter(), instrumentations: [getNodeAutoInstrumentations()] }); -sdk.start() +sdk + .start() + .then(() => { + console.log('Tracing initialized'); + }) + .catch((error) => console.log('Error initializing tracing', error)); {{< /tab >}} {{< tab JavaScript >}} @@ -184,17 +174,18 @@ sdk.start() // Require dependencies const opentelemetry = require("@opentelemetry/sdk-node"); const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node"); -const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api'); - -// For troubleshooting, set the log level to DiagLogLevel.DEBUG -diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO); const sdk = new opentelemetry.NodeSDK({ traceExporter: new opentelemetry.tracing.ConsoleSpanExporter(), instrumentations: [getNodeAutoInstrumentations()] }); -sdk.start() +sdk + .start() + .then(() => { + console.log('Tracing initialized'); + }) + .catch((error) => console.log('Error initializing tracing', error)); {{< /tab >}} {{< /tabpane >}} @@ -321,8 +312,8 @@ telemetry backends. ## Troubleshooting -Did something go wrong? Remember that you need to explicitly enable logging in -order to see logs from OpenTelemetry: +Did something go wrong? You can enable diagnostic logging to validate that +OpenTelemetry is initialized correctly: {{< tabpane langEqualsHeader=true >}} From b4ea4ee77a3a3491d4d6aca07ef1ff2a77a7c2bf Mon Sep 17 00:00:00 2001 From: OpenTelemetry Bot <107717825+opentelemetrybot@users.noreply.github.com> Date: Fri, 10 Mar 2023 10:53:54 -0800 Subject: [PATCH 06/25] Update opentelemetry-java version to 1.24.0 (#2480) --- content/en/docs/instrumentation/java/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/instrumentation/java/_index.md b/content/en/docs/instrumentation/java/_index.md index c5cbfa3d0771..ed36e2aebe7c 100644 --- a/content/en/docs/instrumentation/java/_index.md +++ b/content/en/docs/instrumentation/java/_index.md @@ -6,7 +6,7 @@ description: >- aliases: [/java, /java/metrics, /java/tracing] weight: 18 cascade: - javaVersion: 1.23.1 + javaVersion: 1.24.0 --- {{% lang_instrumentation_index_head java /%}} From a7989db9ba2c95ce20bfaaf936244379a1520554 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 11 Mar 2023 12:33:45 -0500 Subject: [PATCH 07/25] Add entry for missing OTel component color (#2481) --- assets/scss/_registry.scss | 6 ++++++ assets/scss/_variables_project.scss | 1 + 2 files changed, 7 insertions(+) diff --git a/assets/scss/_registry.scss b/assets/scss/_registry.scss index 9fc66454c4ba..078821959705 100644 --- a/assets/scss/_registry.scss +++ b/assets/scss/_registry.scss @@ -21,4 +21,10 @@ background-color: inherit; border: solid 1px; } + + // Default color attributes, in case we miss a component definition above; + // which has happened, see https://github.com/open-telemetry/opentelemetry.io/pull/2481. + $default-otel-badge-bg: $yellow; + color: color-contrast($default-otel-badge-bg); + background-color: $default-otel-badge-bg; } diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 28b6e56d0b5e..90fc12dfcb90 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -26,6 +26,7 @@ $otel-component-colors: ( 'processor': #d32c42, 'python': #3572a5, 'receiver': #742cd3, + 'resource-detector': green, 'ruby': #701516, 'rust': #dea584, 'swift': #de5d43, From 23b2939a58083735a0a8dd94277c3cdf08781495 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 11 Mar 2023 12:56:12 -0500 Subject: [PATCH 08/25] Report issue if an external link is used to a local spec page (#2477) --- layouts/_default/_markup/render-link.html | 12 +++++++++--- scripts/content-modules/adjust-pages.pl | 8 +++++++- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index f26804dbd774..f15f73f981cf 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -1,8 +1,14 @@ {{ $isExternal := hasPrefix .Destination "http" -}} -{{ if and $isExternal (findRE "^https://opentelemetry.io/\\w" .Destination) -}} - {{ errorf "%s: use a local path, not an external URL, for the following reference to a local page: %s" - .Page.File.Path .Destination -}} +{{ if $isExternal -}} + {{ if findRE "^https://opentelemetry.io/\\w" .Destination -}} + {{ errorf "%s: use a local path, not an external URL, for the following reference to a site local page: %s" + .Page.File.Path .Destination -}} + {{ else if findRE "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/specification/\\w" .Destination -}} + {{ errorf "%s: use a local path, not an external URL, for the following reference to a local specification page: %s" + .Page.File.Path .Destination -}} + {{ end -}} {{ end -}} + {{/* Until Hugo supports hook params (https://github.com/gohugoio/hugo/issues/6670), we'll inspect .Text. */ -}} {{ $noExternalIcon := in .Text "hk-no-external-icon" -}} Date: Sat, 11 Mar 2023 15:13:54 -0500 Subject: [PATCH 09/25] Copyedits of concepts/components.md (#2483) --- content/en/docs/concepts/components.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/content/en/docs/concepts/components.md b/content/en/docs/concepts/components.md index cf0b88ddca6b..07f05947787e 100644 --- a/content/en/docs/concepts/components.md +++ b/content/en/docs/concepts/components.md @@ -1,18 +1,17 @@ --- title: Components -description: >- - The main components that make up OpenTelemetry +description: The main components that make up OpenTelemetry weight: 20 --- OpenTelemetry is currently made up of several main components: - [Cross-language specification](/docs/reference/specification/) -- [The OpenTelemetry Collector](/docs/collector) -- [Per-language SDKs](/docs/instrumentation) +- [OpenTelemetry Collector](/docs/collector/) +- [Per-language SDKs](/docs/instrumentation/) - [Per-language instrumentation libraries](/docs/concepts/instrumenting-library/) -- [Per-language Automatic Instrumentation](/docs/concepts/instrumenting/#automatic-instrumentation) -- [K8s Operator](/docs/k8s-operator) +- [Per-language automatic instrumentation](/docs/concepts/instrumenting/#automatic-instrumentation) +- [K8s Operator](/docs/k8s-operator/) OpenTelemetry lets you replace the need for vendor-specific SDKs and tools for generating and exporting telemetry data. @@ -31,7 +30,7 @@ following: - **Data:** Defines the OpenTelemetry Protocol (OTLP) and vendor-agnostic semantic conventions that a telemetry backend can provide support for. -For more information, see the [Specification](/docs/reference/specification/). +For more information, see the [specification](/docs/reference/specification/). Additionally, extensively-commented protobuf interface files for API concepts can be found in the @@ -41,7 +40,7 @@ can be found in the The OpenTelemetry Collector is a vendor-agnostic proxy that can receive, process, and export telemetry data. It supports receiving telemetry data in -multiple formats (e.g., OTLP, Jaeger, Prometheus, as well as many +multiple formats (for example, OTLP, Jaeger, Prometheus, as well as many commercial/proprietary tools) and sending data to one or more backends. It also supports processing and filtering telemetry data before it gets exported. Collector contrib packages bring support for more data formats and vendor @@ -57,7 +56,7 @@ preferred backend. These SDKs also let you incorporate instrumentation libraries for common libraries and frameworks that you can use to connect to manual instrumentation in your application. -For more information, see [Instrumenting](/docs/concepts/instrumenting). +For more information, see [Instrumenting](/docs/concepts/instrumenting/). ## Instrumentation Libraries @@ -89,4 +88,4 @@ The OpenTelemetry Operator is an implementation of a Kubernetes Operator. The operator manages the OpenTelemetry Collector and auto-instrumentation of the workloads using OpenTelemetry. -For more information, see [K8s Operator](/docs/k8s-operator/) +For more information, see [K8s Operator](/docs/k8s-operator/). From 102cabd0488f88fd5316e4de477403a0a1375797 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 11 Mar 2023 15:20:22 -0500 Subject: [PATCH 10/25] Copyedits of collector-receiver-snmp.yml (#2484) --- .vscode/cspell.json | 1 + data/registry/collector-receiver-snmp.yml | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.vscode/cspell.json b/.vscode/cspell.json index c141c6164f72..00eaa9d769df 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -29,6 +29,7 @@ "relref", "roadmap", "runtimes", + "SNMP", "subdir", "tabpane", "tocstop", diff --git a/data/registry/collector-receiver-snmp.yml b/data/registry/collector-receiver-snmp.yml index cc0e2675055a..f5c30c2ea8c6 100644 --- a/data/registry/collector-receiver-snmp.yml +++ b/data/registry/collector-receiver-snmp.yml @@ -9,8 +9,8 @@ tags: repo: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/snmpreceiver license: Apache 2.0 description: - This receiver fetches stats from a SNMP enabled host using a [golang snmp - client](https://github.com/gosnmp/gosnmp). Metrics are collected based upon - different configurations in the config file. + This receiver fetches stats from an SNMP-enabled host using the [Go SNMP + client](https://github.com/gosnmp/gosnmp). Metrics are collected based on + configuration settings. authors: OpenTelemetry Authors otVersion: latest From ea9c4cbe84a72c06f756252391dcc796f83c10c5 Mon Sep 17 00:00:00 2001 From: Radoslav Husar Date: Sat, 11 Mar 2023 21:57:13 +0100 Subject: [PATCH 11/25] Update getting-started.md - fix MacOS Packaging instructions (#2486) --- content/en/docs/collector/getting-started.md | 23 ++++++++++---------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/content/en/docs/collector/getting-started.md b/content/en/docs/collector/getting-started.md index 8b3a68013c2e..f7bc125153c8 100644 --- a/content/en/docs/collector/getting-started.md +++ b/content/en/docs/collector/getting-started.md @@ -225,18 +225,19 @@ sudo journalctl -u otelcol packaged as gzipped tarballs (`.tar.gz`) and will need to be unpacked with a tool that supports this compression format: -{{< ot-tabs Intel ARM >}} {{< ot-tab lang="console">}} $ curl -O -L -https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% -param collectorVersion -%}}/otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz $ tar -xvf -otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz {{< /ot-tab >}} - -{{< ot-tab lang="console">}} $ curl -O -L -https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% -param collectorVersion -%}}/otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz $ tar -xvf -otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz {{< /ot-tab >}} + +{{< ot-tabs Intel ARM >}} +{{< ot-tab lang="console">}} +$ curl -O -L https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz +$ tar -xvf otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz +{{< /ot-tab >}} + +{{< ot-tab lang="console">}} +$ curl -O -L https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz +$ tar -xvf otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz +{{< /ot-tab >}} {{< /ot-tabs >}} + Every Collector release includes an `otelcol` executable that you can run after unpacking. From d086d4d9128f27c079eac1ffe0d4b3c457c5a1cf Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 11 Mar 2023 19:47:57 -0500 Subject: [PATCH 12/25] Collector getting-started copyedits (#2487) --- .vscode/cspell.json | 1 + content/en/docs/collector/getting-started.md | 145 +++++++++---------- 2 files changed, 73 insertions(+), 73 deletions(-) diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 00eaa9d769df..be34e728b61f 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -10,6 +10,7 @@ "daemonset", "Dynatrace", "Grafana", + "gzipped", "hugo", "initializers", "Istio", diff --git a/content/en/docs/collector/getting-started.md b/content/en/docs/collector/getting-started.md index f7bc125153c8..299e8ad46ce6 100644 --- a/content/en/docs/collector/getting-started.md +++ b/content/en/docs/collector/getting-started.md @@ -1,6 +1,8 @@ --- title: Getting Started -spelling: cSpell:ignore dpkg GOARCH journalctl kubectl +spelling: + - cSpell:ignore darwin dpkg GOARCH journalctl kubectl linux otelcorecol pprof + - cSpell:ignore zpages weight: 1 --- @@ -11,7 +13,7 @@ and [Deployment Methods][] page. ## Demo Deploys a load generator, agent and gateway as well as Jaeger, Zipkin and -Prometheus back-ends. More information can be found on the demo [README.md][] +Prometheus back-ends. More information can be found on the demo [README.md][]. ```sh git clone git@github.com:open-telemetry/opentelemetry-collector-contrib.git --depth 1; \ @@ -27,26 +29,26 @@ run. {{< ot-tabs DockerHub ghcr.io >}} -{{< ot-tab lang="console">}} -$ docker pull otel/opentelemetry-collector:{{% param collectorVersion %}} -$ docker run otel/opentelemetry-collector:{{% param collectorVersion %}} +{{< ot-tab lang="sh" >}} +docker pull otel/opentelemetry-collector:{{% param collectorVersion %}} +docker run otel/opentelemetry-collector:{{% param collectorVersion %}} {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ docker pull ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}} -$ docker run ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}} +{{< ot-tab lang="sh" >}} +docker pull ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}} +docker run ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}} {{< /ot-tab >}} {{< /ot-tabs >}} To load your custom configuration `config.yaml` from your current working directory, mount that file as a volume: {{< ot-tabs DockerHub ghcr.io >}} -{{< ot-tab lang="console">}} -$ docker run -v $(pwd)/config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector:{{% param collectorVersion %}} +{{< ot-tab lang="sh" >}} +docker run -v $(pwd)/config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector:{{% param collectorVersion %}} {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}} +{{< ot-tab lang="sh" >}} +docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}} {{< /ot-tab >}} {{< /ot-tabs >}} @@ -57,7 +59,6 @@ You can add OpenTelemetry collector to your existing `docker-compose.yaml` like the following: ```yaml -# Collector otel-collector: image: otel/opentelemetry-collector command: [--config=/etc/otel-collector-config.yaml] @@ -93,7 +94,7 @@ automatic sidecar injection into deployments, among others. ## Nomad Reference job files to deploy the Collector as an agent, gateway and in the full -demo can be found at [Getting Started with OpenTelemetry on HashiCorp Nomad][] +demo can be found at [Getting Started with OpenTelemetry on HashiCorp Nomad][]. ## Linux Packaging @@ -101,7 +102,7 @@ Every Collector release includes APK, DEB and RPM packaging for Linux amd64/arm64/i386 systems. The packaging includes a default configuration that can be found at `/etc/otelcol/config.yaml` post-installation. -> Please note that systemd is required for automatic service configuration +> Note: `systemd` is required for automatic service configuration. ### APK Installation @@ -111,25 +112,25 @@ run. {{< ot-tabs AMD64 ARM64 i386 >}} -{{< ot-tab lang="console">}} -$ apk update -$ apk add wget shadow -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.apk -$ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_amd64.apk +{{< ot-tab lang="sh" >}} +apk update +apk add wget shadow +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.apk +apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_amd64.apk {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ apk update -$ apk add wget shadow -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.apk -$ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_arm64.apk +{{< ot-tab lang="sh" >}} +apk update +apk add wget shadow +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.apk +apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_arm64.apk {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ apk update -$ apk add wget shadow -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.apk -$ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_386.apk +{{< ot-tab lang="sh" >}} +apk update +apk add wget shadow +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.apk +apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_386.apk {{< /ot-tab >}} {{< /ot-tabs >}} @@ -142,25 +143,25 @@ run and `amd64` with the appropriate architecture. {{< ot-tabs AMD64 ARM64 i386 >}} -{{< ot-tab lang="console">}} -$ sudo apt-get update -$ sudo apt-get -y install wget systemctl -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.deb -$ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_amd64.deb +{{< ot-tab lang="sh" >}} +sudo apt-get update +sudo apt-get -y install wget systemctl +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.deb +sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_amd64.deb {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ sudo apt-get update -$ sudo apt-get -y install wget systemctl -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.deb -$ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_arm64.deb +{{< ot-tab lang="sh" >}} +sudo apt-get update +sudo apt-get -y install wget systemctl +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.deb +sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_arm64.deb {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ sudo apt-get update -$ sudo apt-get -y install wget systemctl -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.deb -$ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_386.deb +{{< ot-tab lang="sh" >}} +sudo apt-get update +sudo apt-get -y install wget systemctl +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.deb +sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_386.deb {{< /ot-tab >}} {{< /ot-tabs >}} @@ -173,25 +174,25 @@ run and `x86_64` with the appropriate architecture. {{< ot-tabs AMD64 ARM64 i386 >}} -{{< ot-tab lang="console">}} -$ sudo yum update -$ sudo yum -y install wget systemctl -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.rpm -$ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_amd64.rpm +{{< ot-tab lang="sh" >}} +sudo yum update +sudo yum -y install wget systemctl +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.rpm +sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_amd64.rpm {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ sudo yum update -$ sudo yum -y install wget systemctl -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.rpm -$ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_arm64.rpm +{{< ot-tab lang="sh" >}} +sudo yum update +sudo yum -y install wget systemctl +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.rpm +sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_arm64.rpm {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ sudo yum update -$ sudo yum -y install wget systemctl -$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.rpm -$ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_386.rpm +{{< ot-tab lang="sh" >}} +sudo yum update +sudo yum -y install wget systemctl +wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.rpm +sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_386.rpm {{< /ot-tab >}} {{< /ot-tabs >}} @@ -221,20 +222,20 @@ sudo journalctl -u otelcol ## MacOS Packaging -[MacOS releases][] are available for Intel- & ARM-based systems. They are +MacOS [releases][] are available for Intel- & ARM-based systems. They are packaged as gzipped tarballs (`.tar.gz`) and will need to be unpacked with a tool that supports this compression format: {{< ot-tabs Intel ARM >}} -{{< ot-tab lang="console">}} -$ curl -O -L https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz -$ tar -xvf otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz +{{< ot-tab lang="sh" >}} +curl -O -L https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz +tar -xvf otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz {{< /ot-tab >}} -{{< ot-tab lang="console">}} -$ curl -O -L https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz -$ tar -xvf otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz +{{< ot-tab lang="sh" >}} +curl -O -L https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz +tar -xvf otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz {{< /ot-tab >}} {{< /ot-tabs >}} @@ -244,7 +245,7 @@ unpacking. ## Windows Packaging -[Windows releases][] are packaged as gzipped tarballs (`.tar.gz`) and will need +Windows [releases][] are packaged as gzipped tarballs (`.tar.gz`) and will need to be unpacked with a tool that supports this compression format. Every Collector release includes an `otelcol.exe` executable that you can run @@ -284,8 +285,8 @@ terminal window as well. **Note:** The commands shown above demonstrate the process in a bash shell. These commands may vary slightly for other shells. -[data collection]: /docs/concepts/data-collection -[deployment methods]: ../deployment +[data collection]: /docs/concepts/data-collection/ +[deployment methods]: ../deployment/ [readme.md]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/examples/demo [opentelemetry helm charts]: @@ -294,7 +295,5 @@ These commands may vary slightly for other shells. https://github.com/open-telemetry/opentelemetry-operator [getting started with opentelemetry on hashicorp nomad]: https://github.com/hashicorp/nomad-open-telemetry-getting-started -[macos releases]: - https://github.com/open-telemetry/opentelemetry-collector-releases/releases -[windows releases]: +[releases]: https://github.com/open-telemetry/opentelemetry-collector-releases/releases From d9acfd25ea8fc3a5e9c9f762b46494a98cdaf06a Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Mon, 13 Mar 2023 15:32:36 +0100 Subject: [PATCH 13/25] Update metrics overview page (#2493) --- content/en/docs/concepts/signals/metrics.md | 38 ++++++++++++++------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/content/en/docs/concepts/signals/metrics.md b/content/en/docs/concepts/signals/metrics.md index 47412d562ac4..127c64c73966 100644 --- a/content/en/docs/concepts/signals/metrics.md +++ b/content/en/docs/concepts/signals/metrics.md @@ -14,22 +14,36 @@ indicators impact user experience or the business. Collected data can be used to alert of an outage or trigger scheduling decisions to scale up a deployment automatically upon high demand. -OpenTelemetry defines three _metric instruments_ today: +OpenTelemetry defines six _metric instruments_ today which can be created +through the OpenTelemetry API: -- **counter**: a value that is summed over time -- you can think of this like an - odometer on a car; it only ever goes up. -- **measure**: a value that is aggregated over time. This is more akin to the - trip odometer on a car, it represents a value over some defined range. -- **observer**: captures a current set of values at a particular point in time, - like a fuel gauge in a vehicle. +- **Counter**: A value that accumulates over time -- you can think of this like + an odometer on a car; it only ever goes up. +- **Asynchronous Counter**: Same as the **Counter**, but is collected once for + each export. Could be used if you don't have access to the continous + increments, but only to the aggregated value. +- **UpDownCounter**: A value that accumulates over time, but can also go down + again. An example could be a queue length, it will increase and decrease with + the number of work items in the queue. +- **Asynchronous UpDownCounter**: Same as the **UpDownCounter**, but is + collected once for each export. Could be used if you don't have access to the + continous changes, but only to the aggregated value (e.g., current queue + size). +- **(Asynchronous) Gauge**: Measures a current value at the time it is read. An + example would be the fuel gauge in a vehicle. Gauges are _always_ + asynchronous. +- **Histogram**: A histogram is a client-side aggregation of values, e.g., + request latencies. A histogram is likely a good choice if you have a lot of + values, and are not interested in every individual value, but a statistic + about these values (e.g., How many requests take fewer than 1s?) -In addition to the three metric instruments, the concept of _aggregations_ is an +In addition to the metric instruments, the concept of _aggregations_ is an important one to understand. An aggregation is a technique whereby a large number of measurements are combined into either exact or estimated statistics -about metric events that took place during a time window. The OpenTelemetry API -itself does not allow you to specify these aggregations, but provides some -default ones. In general, the OpenTelemetry SDK provides for common aggregations -(such as sum, count, last value, and histograms) that are supported by +about metric events that took place during a time window. The OTLP protocol +transports such aggreagated metrics. The OpenTelemetry API provides a default +aggregation for each instrument which can be overridden using the Views API. The +OpenTelemetry project aims to provide default aggregations that are supported by visualizers and telemetry backends. Unlike request tracing, which is intended to capture request lifecycles and From 23b6d15c490cdb295311eb09e1f940da76030db4 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 13 Mar 2023 08:08:32 -0700 Subject: [PATCH 14/25] Add sampling doc for JS (#2482) Co-authored-by: Patrice Chalin Co-authored-by: Severin Neumann Co-authored-by: Marc Pichler --- .../en/docs/instrumentation/js/sampling.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 content/en/docs/instrumentation/js/sampling.md diff --git a/content/en/docs/instrumentation/js/sampling.md b/content/en/docs/instrumentation/js/sampling.md new file mode 100644 index 000000000000..31aa6a339700 --- /dev/null +++ b/content/en/docs/instrumentation/js/sampling.md @@ -0,0 +1,94 @@ +--- +title: Sampling +weight: 9 +--- + +[Sampling](/docs/concepts/sampling/) is a process that restricts the amount of +traces that are generated by a system. The JavaScript SDK offers several +[head samplers](/docs/concepts/sampling#head-sampling). + +## Default behavior + +By default, all spans are sampled, and thus, 100% of traces are sampled. If you +do not need to manage data volume, don't bother setting a sampler. + +## TraceIDRatioBasedSampler + +When sampling, the most common head sampler to use is the +TraceIdRatioBasedSampler. It deterministically samples a percentage of traces +that you pass in as a parameter. + +### Environment Variables + +You can configure the TraceIdRatioBasedSampler with environment variables: + +```shell +export OTEL_TRACES_SAMPLER="traceidratio" +export OTEL_TRACES_SAMPLER_ARG="0.1" +``` + +This tells the SDK to sample spans such that only 10% of traces get created. + +### Node.js + +You can also configure the TraceIdRatioBasedSampler in code. Here's an example +for Node.js: + + +{{< tabpane lang=shell persistLang=false >}} + +{{< tab TypeScript >}} +import { TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-node'; + +const samplePercentage = 0.1; + +const sdk = new NodeSDK({ + // Other SDK configuration parameters go here + sampler: new TraceIdRatioBasedSampler(samplePercentage), +}); +{{< /tab >}} + +{{< tab JavaScript >}} +const { TraceIdRatioBasedSampler } = require('@opentelemetry/sdk-trace-node'); + +const samplePercentage = 0.1; + +const sdk = new NodeSDK({ + // Other SDK configuration parameters go here + sampler: new TraceIdRatioBasedSampler(samplePercentage), +}); +{{< /tab >}} + +{{< /tabpane >}} + + +### Browser + +You can also configure the TraceIdRatioBasedSampler in code. Here's an example +for browser apps: + + +{{< tabpane lang=shell persistLang=false >}} + +{{< tab TypeScript >}} +import { WebTracerProvider, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-web'; + +const samplePercentage = 0.1; + +const provider = new WebTracerProvider({ + sampler: new TraceIdRatioBasedSampler(samplePercentage), +}); +{{< /tab >}} + +{{< tab JavaScript >}} +const { WebTracerProvider, TraceIdRatioBasedSampler } = require('@opentelemetry/sdk-trace-web'); + +const samplePercentage = 0.1; + +const provider = new WebTracerProvider({ + sampler: new TraceIdRatioBasedSampler(samplePercentage), +}); +{{< /tab >}} + +{{< /tabpane >}} + From 69e6380e85254dc708a63f99084fa3ddec794d94 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 13 Mar 2023 08:10:49 -0700 Subject: [PATCH 15/25] Elaborate on traces a little more in the traces concept doc (#2467) Co-authored-by: Severin Neumann Co-authored-by: Severin Neumann --- content/en/docs/concepts/signals/traces.md | 25 ++++++++++++++-------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/content/en/docs/concepts/signals/traces.md b/content/en/docs/concepts/signals/traces.md index f618f2378ae5..42470d9d1388 100644 --- a/content/en/docs/concepts/signals/traces.md +++ b/content/en/docs/concepts/signals/traces.md @@ -4,12 +4,12 @@ weight: 1 --- [**Traces**](/docs/concepts/observability-primer/#distributed-traces) give us -the big picture of what happens when a request is made by user or an -application. OpenTelemetry provides us with a way to implement Observability -into our code in production by tracing our microservices and related -applications. +the big picture of what happens when a request is made to an application. +Whether your application is a monolith with a single database or a sophisticated +mesh of services, traces are essential to understanding the full "path" a +request takes in your application. -Sample Trace: +Consider the following example trace that tracks three units of work: ```json { @@ -87,10 +87,17 @@ Sample Trace: } ``` -This sample trace output has three items, named "Hello-Greetings", -"Hello-Salutations" and "Hello". Because each request's context has the same -trace ID, all of the information can be tied together. This provides a trail -through the requests' various routes, timestamps and other attributes. +This sample trace output has three distinct log-like items, called +[Spans](#spans-in-opentelemetry), named `Hello-Greetings`, `Hello-Salutations` +and `Hello`. Because each request's context has the same `trace_id`, they are +considered to be a part of the same Trace. + +Another think you'll note is that each Span of this example Trace looks like a +structured log. That's because it kind of is! One way to think of Traces is that +they're a collection of structured logs with context, correlation, hierarchy, +and more baked in. However, these "structured logs" can come from different +processes, services, VMs, data centers, and so on. This is what allows tracing +to represent an end-to-end view of any system. To understand how tracing in OpenTelemetry works, let's look at a list of components that will play a part in instrumenting our code: From 6a4b374c2ea46abf4c93873e57c36cb8a167168f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 13 Mar 2023 11:57:01 -0400 Subject: [PATCH 16/25] Docsy upgrade including Bootstrap v5 (#2490) --- assets/js/registrySearch.js | 2 +- assets/scss/_styles_project.scss | 79 +++++++--- content/en/_index.md | 24 +-- content/en/docs/getting-started/_index.md | 4 +- content/en/ecosystem/registry/_index.md | 7 +- content/en/status.md | 2 +- layouts/shortcodes/registry-search-form.html | 146 ++++++++++--------- static/refcache.json | 28 ++++ themes/docsy | 2 +- 9 files changed, 189 insertions(+), 105 deletions(-) diff --git a/assets/js/registrySearch.js b/assets/js/registrySearch.js index a5f95c843f95..1aac4716f391 100644 --- a/assets/js/registrySearch.js +++ b/assets/js/registrySearch.js @@ -200,7 +200,7 @@ function setInput(key, value) { // Filters items based on language and component filters function updateFilters() { - let allItems = [...document.getElementsByClassName('media')]; + let allItems = [...document.getElementsByClassName('registry-entry')]; if (selectedComponent === 'all' && selectedLanguage === 'all') { allItems.forEach((element) => element.classList.remove('d-none')); } else { diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 612d6b5f38fc..4323fa2f0ae6 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -35,6 +35,10 @@ > a { @extend .btn; margin: 0.25rem; + + &:hover { + text-decoration: none; + } } } } @@ -109,42 +113,47 @@ padding-top: 1rem; } -// Homepage -#cncf { - width: 100%; - text-align: center; - - p { - font-size: 18px; - margin-bottom: 0; +.td-home { + .td-main { + // Remove the gap between the last block shortcode and the footer (on homepage) + flex-grow: 0; } - img { - margin-top: 1rem; - width: 20rem; - max-width: 80%; + .cncf { + text-align: center; + + p { + font-size: 1.2rem; + margin-bottom: 0; + } + + img { + width: 20rem; + padding-top: 1rem; + max-width: 80%; + } + + a.external-link:after { + display: none; + } } +} - a.external-link:after { - display: none; +.td-default, // E.g.: Homepage, Status, Search, 404; excludes navbar +.td-section main, .td-page main, // Doc and blog main content without left/right navs +.td-page-meta { + a:hover { + text-decoration: underline; } } .td-box--dark a, .td-box--primary a { - color: lighten($primary, 25%) !important; - - &:hover { - text-decoration: underline; - } + color: lighten($primary, 25%) !important; // TODO: upstream } .td-box--secondary a { - color: darken($primary, 25%) !important; - - &:hover { - text-decoration: underline; - } + color: darken($primary, 25%) !important; // TODO: upstream } // Adjust anchors scroll snap (https://github.com/open-telemetry/opentelemetry.io/pull/348) @@ -269,3 +278,25 @@ } } } + +// Registry + +.td-section.registry { + .td-outer { + height: auto; + } + + .registry-entry { + display: flex; + align-items: flex-start; + padding-bottom: 0.5rem; + + .h5 { + margin-bottom: 0.2rem; + } + + &-body { + flex: 1; + } + } +} diff --git a/content/en/_index.md b/content/en/_index.md index c38d759d5296..af576dcfa3bd 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -1,5 +1,8 @@ --- title: OpenTelemetry +description: >- + High-quality, ubiquitous, and portable telemetry to enable effective + observability show_banner: true developer_note: The blocks/cover shortcode (used below) will use as a background image any @@ -10,9 +13,14 @@ spelling: cSpell:ignore shortcode
{{< blocks/cover image_anchor="top" height="max" color="primary" >}} - -## High-quality, ubiquitous, and portable telemetry to enable effective observability + +![OpenTelemetry](/img/logos/opentelemetry-horizontal-color.svg) +{.otel-logo} + + +{{% param description %}} +{.display-6}
@@ -43,7 +51,7 @@ you analyze your software's performance and behavior. {{% /blocks/lead %}} -{{% blocks/section color="dark" %}} +{{% blocks/section color="dark" type="row" %}} {{% blocks/feature icon="fas fa-chart-line" title="Traces, Metrics, Logs"%}} @@ -69,13 +77,10 @@ Installation and integration can be as simple as a few lines of code. {{% /blocks/section %}} -{{% blocks/section color="secondary" %}} - -
+{{% blocks/section color="secondary" type="cncf" %}} -**OpenTelemetry is a [CNCF][] [incubating][] project**. - -Formed through a merger of the OpenTracing and OpenCensus projects. +**OpenTelemetry is a [CNCF][] [incubating][] project**.
Formed through a +merger of the OpenTracing and OpenCensus projects. [![CNCF logo][]][cncf] @@ -83,5 +88,4 @@ Formed through a merger of the OpenTracing and OpenCensus projects. [cncf logo]: /img/logos/cncf-white.svg [incubating]: https://www.cncf.io/projects/ -
{{% /blocks/section %}} diff --git a/content/en/docs/getting-started/_index.md b/content/en/docs/getting-started/_index.md index 46e380a2871a..f84380da1b01 100644 --- a/content/en/docs/getting-started/_index.md +++ b/content/en/docs/getting-started/_index.md @@ -8,7 +8,7 @@ weight: 1 Select a role[^1] to get started: -
+
- [Dev](dev/) - [Ops](ops/) @@ -18,7 +18,7 @@ Select a role[^1] to get started: You can also try out the official [OpenTelemetry Demo][demo] to _see_ what observability with OpenTelemetry looks like! -
+
- [Try the demo][demo] diff --git a/content/en/ecosystem/registry/_index.md b/content/en/ecosystem/registry/_index.md index 40e49c4d4b4c..8b6451fbd839 100644 --- a/content/en/ecosystem/registry/_index.md +++ b/content/en/ecosystem/registry/_index.md @@ -7,6 +7,7 @@ aliases: [/registry/*] type: default layout: registry outputs: [html, json] +body_class: registry weight: 20 --- @@ -18,7 +19,7 @@ weight: 20 {{% /blocks/lead %}} -{{% blocks/section type="section" color="dark" %}} +{{% blocks/section color="dark" %}} ## What do you need? @@ -35,4 +36,8 @@ OpenTelemetry ecosystem. {{% /blocks/section %}} +{{< blocks/section color="white" type="container-lg" >}} + {{}} + +{{< /blocks/section >}} diff --git a/content/en/status.md b/content/en/status.md index e148c905b6ac..9a4f27fd5f6c 100644 --- a/content/en/status.md +++ b/content/en/status.md @@ -5,7 +5,7 @@ aliases: [/project-status, /releases] description: Maturity-level of the main OpenTelemetry components --- -{{% blocks/section type="section" color="white" %}} +{{% blocks/section color="white" %}} ## {{% param title %}} diff --git a/layouts/shortcodes/registry-search-form.html b/layouts/shortcodes/registry-search-form.html index 1f82762ab818..9bb14298cbbf 100644 --- a/layouts/shortcodes/registry-search-form.html +++ b/layouts/shortcodes/registry-search-form.html @@ -26,72 +26,88 @@ {{ end -}} {{ $types = $types | uniq | sort -}} -
-
-
-
-
-
- Search -
- - - +
+ +
+ Search + -
- - -
- - -
-
- - -
-
-
- -
-
+ + -
-
-
    -
      - {{ range $registry -}} -
    • -
      -
      {{ .title }}
       - {{ .description }} - {{ .registryType }} - {{ .language }} -
      -
      • - {{ end -}} -
    -
    -
    - - - {{ partial "script.html" (dict "src" "js/registrySearch.js") -}} + + + + +
    +
    + +
    +
      +
        + {{ range $registry -}} + {{ template "registry-entry" . }} + {{ end -}} +
      +
      + +{{- + $fuseVar := (dict + "description" "${description}" + "language" "${language}" + "registryType" "${registryType}" + "repo" "${repo}" + "title" "${title}" + ) +-}} + + +{{ partial "script.html" (dict "src" "js/registrySearch.js") -}} +
      + +{{- define "registry-entry" -}} +
    • +
      +
      + + {{- .title -}} + +
      + + {{- .description | markdownify -}} + +
      + {{ with .language -}} + {{ . }} + {{- end }} + {{ with .registryType -}} + {{ . }} + {{- end -}} +
      +
      +
      • +{{- end -}} diff --git a/static/refcache.json b/static/refcache.json index 2464aaaa7357..23f0ad82a163 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -135,6 +135,10 @@ "StatusCode": 206, "LastSeen": "2023-02-28T10:57:08.962316-05:00" }, + "https://cdn.jsdelivr.net/npm/mermaid@9.3.0/dist/mermaid.min.js": { + "StatusCode": 206, + "LastSeen": "2023-03-08T11:07:07.821724-05:00" + }, "https://cdnjs.cloudflare.com/ajax/libs/fuse.js/3.2.0/fuse.min.js": { "StatusCode": 200, "LastSeen": "2023-02-15T20:37:53.05407-05:00" @@ -295,6 +299,10 @@ "StatusCode": 206, "LastSeen": "2023-02-15T20:37:19.225321-05:00" }, + "https://code.jquery.com/jquery-3.6.3.min.js": { + "StatusCode": 206, + "LastSeen": "2023-03-08T11:07:01.589189-05:00" + }, "https://collectd.org/wiki/index.php/Binary_protocol": { "StatusCode": 200, "LastSeen": "2023-03-06T12:31:47.297962-05:00" @@ -891,6 +899,22 @@ "StatusCode": 206, "LastSeen": "2023-02-15T21:03:39.650397-05:00" }, + "https://docs.sentry.io/platforms/java/performance/instrumentation/opentelemetry/": { + "StatusCode": 206, + "LastSeen": "2023-03-11T14:17:12.914539-05:00" + }, + "https://docs.sentry.io/platforms/node/performance/instrumentation/opentelemetry/": { + "StatusCode": 206, + "LastSeen": "2023-03-11T14:17:18.015995-05:00" + }, + "https://docs.sentry.io/platforms/python/performance/instrumentation/opentelemetry/": { + "StatusCode": 206, + "LastSeen": "2023-03-11T14:17:23.207009-05:00" + }, + "https://docs.sentry.io/platforms/ruby/performance/instrumentation/opentelemetry/": { + "StatusCode": 206, + "LastSeen": "2023-03-11T14:17:28.309561-05:00" + }, "https://docs.traceloop.dev": { "StatusCode": 206, "LastSeen": "2023-02-26T11:00:42.522142-08:00" @@ -1407,6 +1431,10 @@ "StatusCode": 200, "LastSeen": "2023-02-20T08:04:27.366762-05:00" }, + "https://github.com/gosnmp/gosnmp": { + "StatusCode": 200, + "LastSeen": "2023-03-11T14:17:07.656637-05:00" + }, "https://github.com/hashicorp/nomad-open-telemetry-getting-started": { "StatusCode": 200, "LastSeen": "2023-02-20T07:50:08.100098-05:00" diff --git a/themes/docsy b/themes/docsy index 1a05045c86d9..096aa627f077 160000 --- a/themes/docsy +++ b/themes/docsy @@ -1 +1 @@ -Subproject commit 1a05045c86d9bd1706ec503d14f55ee5a2910f2f +Subproject commit 096aa627f07765e52fcad2831e1e477e24f89780 From e94c9d6fae28f71daff6185129e9d6f4b3d26d48 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 13 Mar 2023 14:48:03 -0400 Subject: [PATCH 17/25] CI: warn about external links to local pages rather than abort with an error (#2497) --- layouts/_default/_markup/render-link.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index f15f73f981cf..b33dde6519a3 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -1,10 +1,10 @@ {{ $isExternal := hasPrefix .Destination "http" -}} {{ if $isExternal -}} {{ if findRE "^https://opentelemetry.io/\\w" .Destination -}} - {{ errorf "%s: use a local path, not an external URL, for the following reference to a site local page: %s" + {{ warnf "%s: use a local path, not an external URL, for the following reference to a site local page: %s" .Page.File.Path .Destination -}} {{ else if findRE "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/specification/\\w" .Destination -}} - {{ errorf "%s: use a local path, not an external URL, for the following reference to a local specification page: %s" + {{ warnf "%s: use a local path, not an external URL, for the following reference to a local specification page: %s" .Page.File.Path .Destination -}} {{ end -}} {{ end -}} From c020f455dbebaf48e87f4ecc80c23113d80d12e0 Mon Sep 17 00:00:00 2001 From: MatthewALHardy Date: Mon, 13 Mar 2023 21:04:43 +0000 Subject: [PATCH 18/25] Update traces.md (#2500) --- content/en/docs/concepts/signals/traces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/concepts/signals/traces.md b/content/en/docs/concepts/signals/traces.md index 42470d9d1388..24d62097763e 100644 --- a/content/en/docs/concepts/signals/traces.md +++ b/content/en/docs/concepts/signals/traces.md @@ -92,7 +92,7 @@ This sample trace output has three distinct log-like items, called and `Hello`. Because each request's context has the same `trace_id`, they are considered to be a part of the same Trace. -Another think you'll note is that each Span of this example Trace looks like a +Another thing you'll note is that each Span of this example Trace looks like a structured log. That's because it kind of is! One way to think of Traces is that they're a collection of structured logs with context, correlation, hierarchy, and more baked in. However, these "structured logs" can come from different From 211e6599abfe65a078f541eb5cf271a6ac7b7146 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 13 Mar 2023 17:30:36 -0400 Subject: [PATCH 19/25] Update dev dependencies in package.json (#2499) --- package.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index 2ec41cd3f503..a10ec94bcab1 100644 --- a/package.json +++ b/package.json @@ -89,13 +89,13 @@ } }, "devDependencies": { - "autoprefixer": "^10.4.13", - "hugo-extended": "0.111.1", - "netlify-cli": "^13.0.0", + "autoprefixer": "^10.4.14", + "hugo-extended": "0.111.3", + "netlify-cli": "^13.1.3", "npm-run-all": "^4.1.5", "postcss": "^8.4.21", "postcss-cli": "^10.1.0", - "prettier": "^2.6.2", + "prettier": "^2.8.4", "textlint": "^13.1.4", "textlint-rule-terminology": "^3.0.4" }, From e5a6c00c242f02a24b1ce0b184a47dc3e9837a11 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 13 Mar 2023 19:55:22 -0400 Subject: [PATCH 20/25] Link homepage demo CTA button to demo docs (#2502) --- content/en/_index.md | 2 +- content/en/ecosystem/demo.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/content/en/_index.md b/content/en/_index.md index af576dcfa3bd..ae1b036aa276 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -25,7 +25,7 @@ spelling: cSpell:ignore shortcode
      - [Learn more](/docs/concepts/) -- [Try the demo](/ecosystem/demo/) +- [Try the demo](/docs/demo/)
      diff --git a/content/en/ecosystem/demo.md b/content/en/ecosystem/demo.md index 5ea92143db84..b258bddfc551 100644 --- a/content/en/ecosystem/demo.md +++ b/content/en/ecosystem/demo.md @@ -7,14 +7,12 @@ description: environment. aliases: - /community/demo - - /docs/demo - /docs/getting-started/demo - /docs/opentelemetry-demo weight: 10 --- -The [OpenTelemetry Demo](https://github.com/open-telemetry/opentelemetry-demo) -does the following: +The [OpenTelemetry Demo](/docs/demo/) does the following: - Provides a realistic example of a distributed system that can be used to demonstrate OpenTelemetry instrumentation and observability. @@ -32,4 +30,7 @@ If you find yourself asking questions like: - How do I consider the [architecture](/docs/demo/architecture/) of a system using OpenTelemetry? -Then check out the [Demo](https://github.com/open-telemetry/opentelemetry-demo). +For more information, see: + +- [Demo documentation](/docs/demo/) +- [Demo repo](https://github.com/open-telemetry/opentelemetry-demo) From 24bcdc68bbc3752136f6197d6fc1837a727c766c Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 14 Mar 2023 02:27:52 -0400 Subject: [PATCH 21/25] Copyedits of demo deployment pages (#2503) --- content/en/docs/demo/docker-deployment.md | 83 +++++++++---------- content/en/docs/demo/kubernetes-deployment.md | 5 +- 2 files changed, 43 insertions(+), 45 deletions(-) diff --git a/content/en/docs/demo/docker-deployment.md b/content/en/docs/demo/docker-deployment.md index 751494ea9b05..cc159a62fc65 100644 --- a/content/en/docs/demo/docker-deployment.md +++ b/content/en/docs/demo/docker-deployment.md @@ -11,40 +11,37 @@ aliases: [/docs/demo/docker_deployment] v2.0.0+ - 4 GB of RAM for the application -## Clone Repo +## Get and run the demo -- Clone the Webstore Demo repository: +1. Clone the Webstore Demo repository: -```shell -git clone https://github.com/open-telemetry/opentelemetry-demo.git -``` + ```shell + git clone https://github.com/open-telemetry/opentelemetry-demo.git + ``` -## Open Folder +2. Change to the demo folder: -- Navigate to the cloned folder: + ```shell + cd opentelemetry-demo/ + ``` -```shell -cd opentelemetry-demo/ -``` +3. Run docker compose to start the demo: -## Run Docker Compose + ```shell + docker compose up --no-build + ``` -- Start the demo: + > **Notes:** + > + > - The `--no-build` flag is used to fetch released docker images from + > [ghcr](https://ghcr.io/open-telemetry/demo) instead of building from + > source. Removing the `--no-build` command line option will rebuild all + > images from source. It may take more than 20 minutes to build if the + > flag is omitted. + > - If you're running on Apple Silicon, run `docker compose build` in order + > to create local images vs. pulling them from the repository. -```shell -docker compose up --no-build -``` - -> **Note:** If you're running on Apple Silicon, please run -> `docker compose build` in order to create local images vs. pulling them from -> the repository. - -**Note:** The `--no-build` flag is used to fetch released docker images from -[ghcr](https://ghcr.io/open-telemetry/demo) instead of building from source. -Removing the `--no-build` command line option will rebuild all images from -source. It may take more than 20 minutes to build if the flag is omitted. - -## Verify the Webstore & the Telemetry +## Verify the Webstore and Telemetry Once the images are built and containers are started you can access: @@ -57,15 +54,15 @@ Once the images are built and containers are started you can access: ## Bring your own backend Likely you want to use the Webstore as a demo application for an observability -backend you already have (e.g. an existing instance of Jaeger, Zipkin, or one of -the [vendor of your choice](/ecosystem/vendors/). +backend you already have (e.g., an existing instance of Jaeger, Zipkin, or one +of the [vendor of your choice](/ecosystem/vendors/). OpenTelemetry Collector can be used to export telemetry data to multiple backends. By default, the collector in the demo application will merge the configuration from two files: -- otelcol-config.yml -- otelcol-config-extras.yml +- `otelcol-config.yml` +- `otelcol-config-extras.yml` To add your backend, open the file [src/otelcollector/otelcol-config-extras.yml](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/otelcollector/otelcol-config-extras.yml) @@ -74,22 +71,22 @@ with an editor. - Start by adding a new exporter. For example, if your backend supports OTLP over HTTP, add the following: -```yaml -exporters: - otlphttp/example: - endpoint: -``` + ```yaml + exporters: + otlphttp/example: + endpoint: + ``` - Then add a new pipeline with your new exporter: -```yaml -service: - pipelines: - traces: - receivers: [otlp] - processors: [batch] - exporters: [otlphttp/example] -``` + ```yaml + service: + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [otlphttp/example] + ``` Vendor backends might require you to add additional parameters for authentication, please check their documentation. Some backends require diff --git a/content/en/docs/demo/kubernetes-deployment.md b/content/en/docs/demo/kubernetes-deployment.md index 6fd17f747990..a89d9f0425e7 100644 --- a/content/en/docs/demo/kubernetes-deployment.md +++ b/content/en/docs/demo/kubernetes-deployment.md @@ -59,9 +59,10 @@ with your Helm chart release name accordingly): kubectl port-forward svc/my-otel-demo-otelcol 4318:4318 ``` -> **Note** > `kubectl port-forward` will proxy the port until the process +> **Note**: `kubectl port-forward` will proxy the port until the process > terminates. You may need to create separate terminal sessions for each use of -> `kubectl port-forward`, and use CTRL-C to terminate the process when done. +> `kubectl port-forward`, and use Ctrl-C to terminate the process +> when done. With the frontendproxy and Collector port-forward set up, you can access: From 5ba8ae20f756c83f05cae54cafb3005639705e42 Mon Sep 17 00:00:00 2001 From: Reese Lee Date: Tue, 14 Mar 2023 09:33:04 -0700 Subject: [PATCH 22/25] Update discussion-group.md (#2501) --- .../en/community/end-user/discussion-group.md | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/content/en/community/end-user/discussion-group.md b/content/en/community/end-user/discussion-group.md index a2597be6e40d..98f73dfdbd17 100644 --- a/content/en/community/end-user/discussion-group.md +++ b/content/en/community/end-user/discussion-group.md @@ -15,7 +15,9 @@ and changes to the project. **New for 2023!** -- APAC (Asia Pacific) sessions begin, come join the first session on January 18! +- Sessions are now available for all regions! +- You can now find summaries of past discussions every month! Search the blog + for "End-User Discussions". - A project maintainer and/or a Governance Committee member will be in attendance at each session to provide additional context, insight, and plans to user questions and feedback. @@ -31,18 +33,20 @@ Here are upcoming sessions, or you can view them on the - **EMEA (Europe, Middle East, and Africa)**: every third Tuesday of the month at 11AM CET (GMT +1), join [here](https://us06web.zoom.us/j/85691064809?pwd=c0VCejh) - - January 17 - - February 21 -- **APAC (Asia Pacific)**: every third Wednesday of the month at 11AM IST (GMT - +5.5), join - [here](https://us06web.zoom.us/j/82702918447?pwd=WllKc0hmdTNuelhFdlhMM1Q3TktSQT09) - - January 18 - - February 15 + - March 21 + - April 18 + - May 16 +- **APAC (Asia Pacific)**: every third Wednesday of the month at 11AM India ST + (GMT +5.5), register [here](https://lu.ma/1w129wgu) to get the Zoom link + - March 15 + - April 19 + - May 17 - **AMER (Americas)**: every third Thursday of the month at 9AM PST (GMT -8), join [here](https://us06web.zoom.us/j/87037874951?pwd=WGo3eUZpeWFZTlhJQXhJeXZhQmwvUT09) - - January 19 - - February 16 + - March 16 + - April 20 + - May 18 Past topics/questions have included: From 4171dda4a983f9300cf089b1670ad08e0ba52162 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 14 Mar 2023 15:27:22 -0400 Subject: [PATCH 23/25] CI: add link-checking GH action, stop failing Netlify build on link-check issues (#2504) --- .github/workflows/check-links.yml | 18 ++++++++++++++++++ netlify.toml | 4 ++-- package.json | 5 +++-- 3 files changed, 23 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/check-links.yml diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml new file mode 100644 index 000000000000..d2d9d1dd32eb --- /dev/null +++ b/.github/workflows/check-links.yml @@ -0,0 +1,18 @@ +name: Check links and refcache # cSpell:ignore refcache + +on: + pull_request: + +jobs: + check-formatting: + name: Check links and refcache + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - run: npm install + - run: npm run build + - run: npm run _check:links + + - name: Fail on uncommitted refcache changes + run: npm run diff:fail diff --git a/netlify.toml b/netlify.toml index 9a59a2d7e2a6..4faece341421 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,9 +1,9 @@ [build] publish = "public" -command = "npm run s build:preview diff:fail" +command = "npm run s build:preview diff:check" [context.production] -command = "npm run s build:production diff:fail" +command = "npm run s build:production diff:check" [[redirects]] from = "https://docs.opentelemetry.io/*" diff --git a/package.json b/package.json index a10ec94bcab1..e10a0edbfb7b 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ "_check:formatting": "npx prettier --check .", "_check:links": "HTMLTEST_ARGS='--log-level 1' npm run __check:links", "_check:links:internal": "npm run __check:links", + "_check:links--warn": "npm run _check:links || (echo; echo 'WARNING: see link-checker output for issues.'; echo)", "_get:no": "echo SKIPPING get operation", "_get:submodule:non-lang": "npm run _get:submodule -- content-modules/opentelemetry-specification themes/docsy", "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}", @@ -33,8 +34,8 @@ "diff:fail": "git diff --name-only --exit-code || (echo; echo 'ERROR: the files above have changed. Locally rerun `npm run test` and commit changes'; echo; git diff | head -100; exit 1)", "get:submodule": "npm run _get:${GET:-submodule}", "make:public": "make public ls-public", - "postbuild:preview": "npm run _check:links", - "postbuild:production": "npm run _check:links", + "postbuild:preview": "npm run _check:links--warn", + "postbuild:production": "npm run _check:links--warn", "prebuild:preview": "run-s _prebuild", "prebuild:production": "run-s _prebuild check:formatting", "prebuild": "npm run _prebuild", From 0680768f56ae4a50ab996270a533bf98e00c9e32 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 14 Mar 2023 14:08:08 -0700 Subject: [PATCH 24/25] Point to rubydoc for ruby API (#2508) --- content/en/docs/instrumentation/ruby/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/instrumentation/ruby/api.md b/content/en/docs/instrumentation/ruby/api.md index fea1ed000f2f..4c2ddf2bab49 100644 --- a/content/en/docs/instrumentation/ruby/api.md +++ b/content/en/docs/instrumentation/ruby/api.md @@ -1,7 +1,7 @@ --- title: API reference linkTitle: API -redirect: https://open-telemetry.github.io/opentelemetry-ruby/ +redirect: https://www.rubydoc.info/gems/opentelemetry-sdk manualLinkTarget: _blank _build: { render: link } weight: 50 From 3a002eb857028b8fcb2f0478895f407ab4c97e0e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 15 Mar 2023 08:28:24 -0400 Subject: [PATCH 25/25] Registry search results: fix Fuse template (#2511) --- assets/scss/_styles_project.scss | 2 +- layouts/shortcodes/registry-search-form.html | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 4323fa2f0ae6..cd2c951ad59b 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -142,7 +142,7 @@ .td-default, // E.g.: Homepage, Status, Search, 404; excludes navbar .td-section main, .td-page main, // Doc and blog main content without left/right navs .td-page-meta { - a:hover { + a:hover:not(.dropdown-item) { text-decoration: underline; } } diff --git a/layouts/shortcodes/registry-search-form.html b/layouts/shortcodes/registry-search-form.html index 9bb14298cbbf..04b44d60f1d5 100644 --- a/layouts/shortcodes/registry-search-form.html +++ b/layouts/shortcodes/registry-search-form.html @@ -90,10 +90,11 @@
      {{- define "registry-entry" -}} +{{ $href := printf "href=%q" .repo | safeHTMLAttr -}}
    • - + {{- .title -}}