Merge branch 'main' into avillela-auto-instr-troubleshooting

.github/CODEOWNERS

@@ -45,6 +45,7 @@ content/en/docs/zero-code/go             @open-telemetry/docs-approvers @open-te
 content/en/docs/zero-code/java/          @open-telemetry/docs-approvers @open-telemetry/java-approvers @open-telemetry/java-instrumentation-approvers
 content/en/docs/zero-code/js/            @open-telemetry/docs-approvers @open-telemetry/javascript-approvers
 content/en/docs/zero-code/net/           @open-telemetry/docs-approvers @open-telemetry/dotnet-approvers @open-telemetry/dotnet-instrumentation-approvers
+content/en/docs/zero-code/python/        @open-telemetry/docs-approvers @open-telemetry/python-approvers
 content/en/docs/zero-code/php/           @open-telemetry/docs-approvers @open-telemetry/php-approvers
 content/en/ecosystem/demo/               @open-telemetry/demo-approvers @open-telemetry/demo-approvers
 content/zh/                              @open-telemetry/docs-maintainers @open-telemetry/docs-zh-approvers

.textlintrc.yml

@@ -8,8 +8,8 @@ filters:
     enablingComment: prettier-ignore-end
   allowlist:
     allow:
-      # Don't check registry .yml file fields for language, repo and tags:
-      - '/^\s*(?:language|repo|name|docs): .*$/m'
+      # Don't check registry .yml file fields for language, repo, url and tags:
+      - '/^\s*(?:language|repo|name|docs|url): .*$/m'
       - /^(?:tags):(\s*-.+$)*/m
       # Hugo template syntax:
       - /{{.*?}}/

content/en/blog/2022/debug-otel-with-otel/index.md

@@ -261,4 +261,4 @@ COPY opentelemetry_module.conf /etc/nginx/conf.d
   https://github.com/open-telemetry/opentelemetry-cpp-contrib/releases/tag/webserver%2Fv1.0.1
 [java]:
   /docs/zero-code/java/agent/configuration/#capturing-http-request-and-response-headers
-[python]: /docs/languages/python/automatic/
+[python]: /docs/zero-code/python/

content/en/blog/2023/end-user-discussions-03.md

@@ -190,7 +190,7 @@ agent to the host metrics receiver for infrastructure monitoring.
   maturing in OTel; for example, the Java JAR agent takes care of instrumenting
   [most libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks)
   that are used by applications. Auto-instrumentation is also available for
-  [Python](/docs/languages/python/automatic/), [.NET](/docs/zero-code/net/), and
+  [Python](/docs/zero-code/python/), [.NET](/docs/zero-code/net/), and
   [Node.js](/docs/zero-code/js/).
 - If you’re using Kubernetes, they can use the
   [OTel operator](https://github.com/open-telemetry/opentelemetry-operator),

content/en/blog/2023/end-user-q-and-a-01.md

@@ -169,7 +169,7 @@ They are hoping to leverage
 [OpenTelemetry’s Exemplars](/docs/specs/otel/metrics/data-model/#exemplars) to
 link traces and metrics.
 
-### How is the organization sending telemetry data to various observability back-ends?
+### How is the organization sending telemetry data to various observability backends?
 
 J’s team uses a combination of the proprietary backend agent and the
 OpenTelemetry Collector (for metrics). They are one of the primary users of

content/en/docs/collector/_index.md

@@ -3,7 +3,7 @@ title: Collector
 description: Vendor-agnostic way to receive, process and export telemetry data.
 aliases: [collector/about]
 cascade:
-  vers: 0.103.0
+  vers: 0.103.1
 weight: 270
 ---
 

content/en/docs/collector/internal-telemetry.md

@@ -332,4 +332,4 @@ with the network or backend receiving the data.
 
 You can monitor data ingress with the `otelcol_receiver_accepted_spans` and
 `otelcol_receiver_accepted_metric_points` metrics and data egress with the
-`otecol_exporter_sent_spans` and `otelcol_exporter_sent_metric_points` metrics.
+`otelcol_exporter_sent_spans` and `otelcol_exporter_sent_metric_points` metrics.

content/en/docs/collector/management.md

@@ -90,7 +90,7 @@ We will set up a simple OpAMP control plane consisting of an example OpAMP
 server and let an OpenTelemetry Collector connect to it via an example OpAMP
 supervisor.
 
-First, clone the `open-telemetry/opamp-go` repo:
+First, clone the `open-telemetry/opamp-go` repository:
 
 ```sh
 git clone https://github.com/open-telemetry/opamp-go.git
@@ -159,7 +159,7 @@ service:
 ```
 
 Now it's time to launch the supervisor (which in turn will launch your
-OpenTelemetry collector):
+OpenTelemetry Collector):
 
 ```console
 $ go run .

content/en/docs/collector/troubleshooting.md

@@ -2,7 +2,7 @@
 title: Troubleshooting
 description: Recommendations for troubleshooting the Collector
 weight: 25
-cSpell:ignore: pprof tracez zpages
+cSpell:ignore: confmap pprof tracez zpages
 ---
 
 On this page, you can learn how to troubleshoot the health and performance of
@@ -359,3 +359,21 @@ container, producing the error message
 the `NO_WINDOWS_SERVICE=1` environment variable must be set to force the
 Collector to start as if it were running in an interactive terminal, without
 attempting to run as a Windows service.
+
+### Collector is experiencing configuration issues
+
+The Collector might experience problems due to configuration issues.
+
+#### Null maps
+
+During configuration resolution of multiple configs, values in earlier configs
+are removed in favor of later configs, even if the later value is null. You can
+fix this issue by
+
+- Using `{}` to represent an empty map, such as `processors: {}` instead of
+  `processors:`.
+- Omitting empty configurations such as `processors:` from the configuration.
+
+See
+[confmap troubleshooting](https://github.com/open-telemetry/opentelemetry-collector/blob/main/confmap/README.md#null-maps)
+for more information.

content/en/docs/concepts/instrumentation/zero-code.md

@@ -49,4 +49,4 @@ Automatic instrumentation is available for the following languages:
 - [Java](/docs/zero-code/java/)
 - [JavaScript](/docs/zero-code/js/)
 - [PHP](/docs/zero-code/php/)
-- [Python](/docs/languages/python/automatic/)
+- [Python](/docs/zero-code/python/)

content/en/docs/concepts/signals/baggage.md

@@ -4,46 +4,52 @@ weight: 4
 description: Contextual information that is passed between signals.
 ---
 
-In OpenTelemetry, Baggage is contextual information that’s passed between spans.
-It's a key-value store that resides alongside span context in a trace, making
-values available to any span created within that trace.
+In OpenTelemetry, Baggage is contextual information that resides next to
+context. Baggage is a key-value store, which means it lets you
+[propagate](/docs/concepts/context-propagation/#propagation) any data you like
+alongside [context](/docs/concepts/context-propagation/#context).
 
-For example, imagine you want to have a `ClientId` attribute on every span in
-your trace, which involves multiple services; however, `ClientId` is only
-available in one specific service. To accomplish your goal, you can use
-OpenTelemetry Baggage to propagate this value across your system.
+Baggage means you can pass data across services and processes, making it
+available to add to [traces](/docs/concepts/signals/traces/),
+[metrics](/docs/concepts/signals/metrics/), or
+[logs](/docs/concepts/signals/logs/) in those services.
 
-OpenTelemetry uses
-[Context Propagation](/docs/concepts/signals/traces/#context-propagation) to
-pass Baggage around, and each of the different library implementations has
-propagators that parse and make that Baggage available without you needing to
-explicitly implement it.
+## Example
 
-![OTel Baggage](/img/otel-baggage.svg)
+Baggage is often used in tracing to propagate additional data across services.
+
+For example, imagine you have a `clientId` at the start of a request, but you'd
+like for that ID to be available on all spans in a trace, some metrics in
+another service, and some logs along the way. Because the trace may span
+multiple services, you need some way to propagate that data without copying the
+`clientId` across many places in your codebase.
 
-## Why does OTel Baggage exist?
+By using
+[Context Propagation](/docs/concepts/signals/traces/#context-propagation) to
+pass baggage across these services, the `clientId` is available to add to any
+additional spans, metrics, or logs. Additionally, instrumentations automatically
+propagate baggage for you.
 
-Baggage provides a uniform way to store and propagate information across a trace
-and other signals. For example, you may want to attach information from your
-application to a span and retrieve that information much later and use it later
-on with another span. However, spans in OpenTelemetry are immutable once
-created, and can be exported before you need information on them later on.
-Baggage allows you to work around this problem by providing a place to store and
-retrieve information.
+![OTel Baggage](/img/otel-baggage.svg)
 
 ## What should OTel Baggage be used for?
 
-Common use cases include information that’s only accessible further up a stack.
-This can include things like Account Identification, User IDs, Product IDs, and
-origin IPs, for example. Passing these down your stack allows you to then add
-them to your Spans in downstream services to make it easier to filter when
-you’re searching in your Observability backend.
+Baggage is best used to include information typically available only at the
+start of a request further downstream. This can include things like Account
+Identification, User IDs, Product IDs, and origin IPs, for example.
+
+Propagating this information using baggage allows for deeper analysis of
+telemetry in a backend. For example, if you include information like a User ID
+on a span that tracks a database call, you can much more easily answer questions
+like "which users are experiencing the slowest database calls?" You can also log
+information about a downstream operation and include that same User ID in the
+log data.
 
 ![OTel Baggage](/img/otel-baggage-2.svg)
 
 ## Baggage security considerations
 
-Sensitive Baggage items could be shared with unintended resources, like
+Sensitive Baggage items can be shared with unintended resources, like
 third-party APIs. This is because automatic instrumentation includes Baggage in
 most of your service’s network requests. Specifically, Baggage and other parts
 of trace context are sent in HTTP headers, making it visible to anyone
@@ -52,22 +58,21 @@ then this risk may not apply, but keep in mind that downstream services could
 propagate Baggage outside your network.
 
 Also, there are no built-in integrity checks to ensure that Baggage items are
-yours, so exercise caution when retrieving them.
+yours, so exercise caution when reading them.
 
-## Baggage is not the same as Span attributes
+## Baggage is not the same as attributes
 
-One important thing to note about Baggage is that it is not a subset of the
-[Span Attributes](/docs/concepts/signals/traces/#attributes). When you add
-something as Baggage, it does not automatically end up on the Attributes of the
-child system’s spans. You must explicitly take something out of Baggage and
-append it as Attributes.
+An important thing to note about baggage is that it is a separate key-value
+store and is unassociated with attributes on spans, metrics, or logs without
+explicitly adding them.
 
-For example, in .NET you might do this:
+To add baggage entries to attributes, you need to explicitly read the data from
+baggage and add it as attributes to your spans, metrics, or logs.
 
-```csharp
-var accountId = Baggage.GetBaggage("AccountId");
-Activity.Current?.SetTag("AccountId", accountId);
-```
+Because a common use cases for Baggage is to add data to
+[Span Attributes](/docs/concepts/signals/traces/#attributes) across a whole
+trace, several languages have Baggage Span Processors that add data from baggage
+as attributes on span creation.
 
 > For more information, see the [baggage specification][].
 

content/en/docs/contributing/blog.md

@@ -79,13 +79,13 @@ Follow these steps to create a post from the template:
 1. Run the following command from the repository root:
 
    ```sh
-   npx hugo new content/en/blog/2023/short-name-for-post.md
+   npx hugo new content/en/blog/2024/short-name-for-post.md
    ```
 
    If your post has images or other assets, run the following command:
 
    ```sh
-   npx hugo new content/en/blog/2023/short-name-for-post/index.md
+   npx hugo new content/en/blog/2024/short-name-for-post/index.md
    ```
 
 1. Edit the Markdown file at the path you provided in the previous command. The

content/en/docs/demo/_index.md

@@ -63,7 +63,7 @@ solve them.
 We'll be adding more scenarios over time.
 
 - Generate a [Product Catalog error](feature-flags) for `GetProduct` requests
-  with product id: `OLJCESPC7Z` using the Feature Flag service
+  with product ID: `OLJCESPC7Z` using the Feature Flag service
 - Discover a memory leak and diagnose it using metrics and traces.
   [Read more](scenarios/recommendation-cache/)
 

content/en/docs/demo/feature-flags.md

@@ -19,7 +19,7 @@ change the `defaultVariant` value in the config file for a given flag to "on".
 | `adServiceManualGc`                 | Ad Service       | Trigger full manual garbage collections in the ad service                                                 |
 | `adServiceHighCpu`                  | Ad Service       | Trigger high cpu load in the ad service. If you want to demo cpu throttling, set cpu resource limits      |
 | `cartServiceFailure`                | Cart Service     | Generate an error for `EmptyCart` 1/10th of the time                                                      |
-| `productCatalogFailure`             | Product Catalog  | Generate an error for `GetProduct` requests with product id: `OLJCESPC7Z`                                 |
+| `productCatalogFailure`             | Product Catalog  | Generate an error for `GetProduct` requests with product ID: `OLJCESPC7Z`                                 |
 | `recommendationServiceCacheFailure` | Recommendation   | Create a memory leak due to an exponentially growing cache. 1.4x growth, 50% of requests trigger growth.  |
 | `paymentServiceFailure`             | Payment Service  | Generate an error when calling the `charge` method.                                                       |
 | `paymentServiceUnreachable`         | Checkout Service | Use a bad address when calling the PaymentService to make it seem like the PaymentService is unavailable. |

content/en/docs/kubernetes/operator/automatic.md

@@ -404,7 +404,7 @@ spec:
 
 #### Learn more {#python-learn-more}
 
-[See the Python agent Configuration docs for more details.](/docs/languages/python/automatic/configuration/#disabling-specific-instrumentations)
+[See the Python agent Configuration docs for more details.](/docs/zero-code/python/configuration/#disabling-specific-instrumentations)
 
 ### Go
 

content/en/docs/kubernetes/operator/troubleshooting/_index.md

@@ -4,5 +4,5 @@ linkTitle: Troubleshooting
 description:
   Contains a collection of tips for troubleshooting various aspects of the
   OpenTelemetry Kubernetes Operator. For example, what to do when the target
-  allocator isn't scraping metrics.
+  allocator is failing to discover scrape targets.
 ---