diff --git a/.gitmodules b/.gitmodules
index e96093a77b6a..45e9719c8d9d 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -27,4 +27,4 @@
[submodule "content-modules/opentelemetry-go"]
path = content-modules/opentelemetry-go
url = https://github.com/open-telemetry/opentelemetry-go
- go-pin = v1.23.0-rc.1-31-geabcef4c2
+ go-pin = v1.27.0
diff --git a/.htmltest.yml b/.htmltest.yml
index 8e64377a99d9..b68ed6e7d7fb 100644
--- a/.htmltest.yml
+++ b/.htmltest.yml
@@ -72,5 +72,5 @@ IgnoreURLs: # list of regexs of paths or URLs to be ignored
- ^https://wikipedia.org/wiki/(S.M.A.R.T|Hop_)
# TODO move into content/en/blog/2023/contributing-to-otel/index.md once https://github.com/open-telemetry/opentelemetry.io/issues/3889 is implemented
- ^https://shorturl.at/vLYZ0$
- # TODO remove while or after fixing https://github.com/open-telemetry/opentelemetry.io/issues/4656
- - ^/docs/specs/otel/versioning-and-stability/#experimental
+ # TODO remove the following temporary ignore rule (@chalin)
+ - ^/en/docs/specs$
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 67979d4ccf84..7ec7a39a8dae 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,243 +3,6 @@
**Thanks for your interest in contributing to
[OpenTelemetry.io](https://opentelemetry.io/)!**
-Follow these guidelines helps to communicate that you respect the time of the
-contributors managing and developing this open source project. In return,
-maintainers and approvers should reciprocate that respect in addressing your
-issue, assessing changes, and helping you finalize your pull requests. In that
-spirit of mutual respect, we endeavor to review incoming issues and pull
-requests, and will close any lingering issues or pull requests after long times
-of inactivity.
-
-## Before you get started
-
-### Code of Conduct
-
-All of your interactions in this project are subject to our
-[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md).
-This includes the creation of issues or pull requests, commenting on issues or
-pull requests, and extends to all interactions in any real-time space, for
-example Slack, Discord, and so on.
-
-### Contributor License Agreement
-
-Review the general
-[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md),
-as it provides additional details, especially that you need to sign a
-Contributor License Agreement (CLA) before you can contribute.
-
-### Found a security issue?
-
-If you discover a security issue, read the
-[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy)
-before opening an issue.
-
-### Found a problem?
-
-If you find a bug or a problem with the content of this repository, or you would
-like to request an enhancement, [create an issue][new-issue].
-
-Before reporting a new issue, make sure that the issue was not already reported
-or fixed by searching through our
-[issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).
-
-When creating a new issue, include a short, meaningful title and a clear
-description. Add as much relevant information as you can, and, if possible, a
-test case.
-
-### Want to work on an existing issue?
-
-This is the best way how you can help us to make our documentation better! Take
-a look at issues tagged with
-[help wanted](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
-and
-[good first issue](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22)
-to find an opportunity to contribute and help us. The good first issue label
-indicates that members have committed to providing extra assistance for new
-contributors.
-
-After picking an issue, read through the existing discussion, ask the
-maintainers if this issue is still relevant and ask all questions you need for
-clarification. Afterwards you can state in a comment that you intend to work on
-this issue and it will be assumed to be yours. We will **not** assign issues to
-non-community members who have already made contributions to the [OpenTelemetry
-organization][org]. After confirmation through a maintainer, plan to provide a
-PR shortly or let maintainers now if you run into any blockers.
-
-## Contributor's guide
-
-To learn how to contribute fixes and new content to this project, read the
-[Contributor's guide](https://opentelemetry.io/docs/contributing/), which
-includes a style guide and useful information on the review process.
-
-## Development
-
-The following instructions will help you to setup a development environment of
-the website.
-
-### Setup
-
-#### Cloud-IDE setup
-
-These instructions are for [Gitpod.io][], adjust as needed for your favorite
-cloud IDE:
-
-1. Fork this repository. For help, see [Fork a repository][fork].
-2. From [gitpod.io/workspaces][], create a new workspace (do this only once) or
- open an existing workspace over your fork. You can also visit a link of the
- form:
- .
-
- > **Note**: If you have the necessary permissions to work from this
- > repository, or just want to look around, open
- > .
-
-Gitpod will automatically install the repo-specific packages for you. You're now
-ready to [build](#build), [serve](#serve) and/or make updates to the website
-files.
-
-#### Local setup
-
-1. [Fork][] and then [clone][] this repository.
-2. **Change** to the repository directory.
-3. **Install or upgrade** to the [**active LTS** release][nodejs-rel] of
- **Node.js**. We recommend using **[nvm][]** to manage your Node
- installation. Under Linux, run the following command (which will
- install/upgrade to the version specified in [.nvmrc][]):
-
- ```sh
- nvm install
- ```
-
- To [install under Windows][nodejs-win], use [nvm-windows][]:
-
- ```cmd
- > nvm install lts && nvm use lts
- ```
-
-4. Get npm packages and other prerequisites:
-
- ```sh
- npm install
- ```
-
-You're now ready to [build](#build), [serve](#serve) and/or make updates to the
-website files.
-
-### Build
-
-To **build** the site run:
-
-```sh
-npm run build
-```
-
-You'll find the generated site files under `public`.
-
-### Serve
-
-To **serve** the site run:
-
-```sh
-npm run serve
-```
-
-The site will be served at [localhost:1313][].
-
-If you need to test [Netlify] redirects, use the following command, and visit
-the site at [localhost:8888][]:
-
-```sh
-npm run serve:netlify
-```
-
-> **Note 1**: The serve command serves files from memory, not from disk.
->
-> **Note 2**: See an error like `too many open files` or `pipe failed` under
-> macOS? You may need to increase the file descriptor limit. See
-> [Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109).
-
-### Content and submodules
-
-The website is built from the following content:
-
-- Files under `content/`, `static/`, etc. per [Hugo][] defaults.
-- Mount points, defined in [hugo.yaml][] under `mounts`. Mounts are either
- directly from git submodules under [content-modules][], or preprocessed
- content from `content-modules` (placed under `tmp/`), and no where else.
-
-[hugo.yaml]:
- https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml
-[content-modules]:
- https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules
-
-### Submodule changes
-
-If you change any content inside of a [content-modules][] submodule, then you'll
-need to **_first_** submit a PR (containing the submodule changes) to the
-submodule's repository. Only after the submodule PR has been accepted, can you
-update the submodule and have the changes appear in this website.
-
-It is easiest to manage your `content-modules` changes by working with the
-repository that the corresponding submodule is linked to, rather than inside the
-submodule itself.
-
-> **For expert contributors**, you can work directly in the submodule. You'll
-> then be able to directly build and serve your (submodule) changes. By default,
-> the CI scripts get submodules on every invocation. To prevent this behavior
-> while you work within a submodule, set the environment variable `GET=no`.
-> You'll also need to `git fetch --unshallow` the submodule before you can
-> submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules.
-
-## Approver and Maintainer practices
-
-This last section includes guidelines and some common practices used by
-approvers and maintainers while doing code reviews:
-
-- PRs with changes to documentation co-owned by a SIG (collector, demo,
- language-specific...) should aim for two approvals: one by a docs approver and
- one by a SIG approver:
- - Doc approver label such PRs with `sig:` and tag the SIG `-approvers`
- group on that PR
- - If no SIG approval is given within a certain grace period (two weeks in
- general, but may be less in urgent cases), docs maintainer may use their own
- judgement to merge that PR
-- If the PR branch is `out-of-date with the base branch`, they do not need to be
- updated continuously: every update triggers all the PR CI checks to be run!
- It's often enough to update them before merging.
-- A PR by non-maintainers should **never** update git sub modules. This happens
- by accident from time to time. Let the PR author know that they should not
- worry about it, we will fix this before merging, but in the future they should
- make sure that they work from an up-to-date fork.
-- If the contributor is having trouble signing the CLA or used the wrong email
- by mistake in one of their commits, ask them to fix the issue or rebase the
- pull request. Worst case scenario, close and re-open the PR to trigger a new
- CLA check.
-- Words unknown to cspell should be added to the cspell ignore list per page by
- PR authors. Only approvers and maintainers will add commonly used terms to the
- global list.
-- When an approver or maintainer won't be available to contribute for an
- extended period of time (more than a few days or a week) or won't be available
- in that period of time, they should communicate this using the
- [#otel-comms](https://cloud-native.slack.com/archives/C02UN96HZH6) channel and
- updating the GitHub status.
-
-[.nvmrc]: .nvmrc
-[clone]:
- https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
-[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
-[gitpod.io]: https://gitpod.io
-[gitpod.io/workspaces]: https://gitpod.io/workspaces
-[hugo]: https://gohugo.io
-[localhost:1313]: http://localhost:1313
-[localhost:8888]: http://localhost:8888
-[netlify]: https://netlify.com
-[new-issue]:
- https://github.com/open-telemetry/opentelemetry.io/issues/new/choose
-[nodejs-rel]: https://nodejs.org/en/about/previous-releases
-[nodejs-win]:
- https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows
-[nvm]:
- https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating
-[nvm-windows]: https://github.com/coreybutler/nvm-windows
-[org]: https://github.com/open-telemetry
+To learn how to contribute new content and fixes to this project, see
+[Contributing](https://opentelemetry.io/docs/contributing/), which includes a
+style guide and useful information on the review process.
diff --git a/README.md b/README.md
index cb27b13cb7c9..3d2973e89694 100644
--- a/README.md
+++ b/README.md
@@ -27,9 +27,16 @@ to the registry][].
## Contributing
-We have curated some issues with the tags [help wanted][] and [good first
-issue][]. This should allow you to quickly find a place to contribute. See [CONTRIBUTING.md][]
-for more information.
+See the [Contributing](https://opentelemetry.io/docs/contributing) page on our
+docs.
+
+## Found a security issue?
+
+If you discover a security issue, read the
+[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy)
+before opening an issue.
+
+## Meetings
We, the OTel Communications SIG, meet every two weeks on Monday at 10:00 PT.
Check out the [OpenTelemetry community calendar][] for the Zoom link and any
@@ -38,16 +45,19 @@ updates to this schedule.
Meeting notes are available as a public [Google doc][]. If you have trouble accessing
the doc, get in touch in the `#otel-comms` channel on [Slack][].
+## Roles
+
Here is a list of community roles with current and previous members:
- Approvers: [@open-telemetry/docs-approvers][]
- - [Fabrizio Ferri-Benedetti](https://github.com/theletterf), Splunk
- [Michael Hausenblas](https://github.com/mhausenblas), Amazon
+ - [Tiffany Hrabusa](https://github.com/tiffany76)
- Maintainers: [@open-telemetry/docs-maintainers][]
- [Austin Parker](https://github.com/austinlparker), Honeycomb
+ - [Fabrizio Ferri-Benedetti](https://github.com/theletterf), Splunk
- [Patrice Chalin](https://github.com/chalin), CNCF
- [Phillip Carter](https://github.com/cartermp), Honeycomb
- [Severin Neumann](https://github.com/svrnm), Cisco
@@ -82,16 +92,12 @@ contributed][contributors]!
[contributing.md]: CONTRIBUTING.md
[contributors]:
https://github.com/open-telemetry/opentelemetry.io/graphs/contributors
-[hugo]: https://gohugo.io
-[netlify]: https://netlify.com
[opentelemetry]: https://opentelemetry.io
[registry]: https://opentelemetry.io/ecosystem/registry/
[opentelemetry community calendar]:
https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com
-[help wanted]:
- https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
-[good first issue]:
- https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[google doc]:
https://docs.google.com/document/d/1wW0jLldwXN8Nptq2xmgETGbGn9eWP8fitvD5njM-xZY/edit?usp=sharing
[slack]: https://slack.cncf.io/
+[hugo]: https://gohugo.io
+[netlify]: https://netlify.com
diff --git a/content-modules/opentelemetry-go b/content-modules/opentelemetry-go
index eabcef4c2da6..5661ff0ded32 160000
--- a/content-modules/opentelemetry-go
+++ b/content-modules/opentelemetry-go
@@ -1 +1 @@
-Subproject commit eabcef4c2da6149b7e6dbbb8b7294402fcc287c1
+Subproject commit 5661ff0ded32cf1b83f1147dae96ca403c198504
diff --git a/content/en/blog/2024/new-otel-features-envoy-istio/index.md b/content/en/blog/2024/new-otel-features-envoy-istio/index.md
index bc94ca7c3c3e..7c030b4140e9 100644
--- a/content/en/blog/2024/new-otel-features-envoy-istio/index.md
+++ b/content/en/blog/2024/new-otel-features-envoy-istio/index.md
@@ -182,7 +182,7 @@ And finally, we configure the `OTEL_RESOURCE_ATTRIBUTES` environment variable
for the Envoy proxies:
```shell
-cat <.*"
+kubectl exec "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" -c ratings -- curl -sS productpage:9080/productpage | grep -o ".*"
```
Then you can check it out on the Jaeger UI -- you should see some traces!
diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md
index 0b300553fb2e..b54a555eca02 100644
--- a/content/en/docs/collector/internal-telemetry.md
+++ b/content/en/docs/collector/internal-telemetry.md
@@ -5,10 +5,11 @@ weight: 25
cSpell:ignore: alloc journalctl kube otecol pprof tracez underperforming zpages
---
-You can monitor the health of any OpenTelemetry Collector instance by checking
+You can inspect the health of any OpenTelemetry Collector instance by checking
its own internal telemetry. Read on to learn about this telemetry and how to
-configure it to help you [troubleshoot](/docs/collector/troubleshooting/)
-Collector issues.
+configure it to help you
+[monitor](#use-internal-telemetry-to-monitor-the-collector) and
+[troubleshoot](/docs/collector/troubleshooting/) the Collector.
## Activate internal telemetry in the Collector
@@ -97,9 +98,9 @@ critical analysis.
### Configure internal logs
Log output is found in `stderr`. You can configure logs in the config
-`service::telemetry::logs`. The [configuration
-options](https://github.com/open-telemetry/opentelemetry-collector/blob/v{{% param
-vers %}}/service/telemetry/config.go) are:
+`service::telemetry::logs`. The
+[configuration options](https://github.com/open-telemetry/opentelemetry-collector/blob/main/service/telemetry/config.go)
+are:
| Field name | Default value | Description |
| ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -133,7 +134,7 @@ journalctl | grep otelcol | grep Error
{{% /tab %}} {{< /tabpane >}}
-## Types of internal observability
+## Types of internal telemetry
The OpenTelemetry Collector aims to be a model of observable service by clearly
exposing its own operational metrics. Additionally, it collects host resource
@@ -272,3 +273,63 @@ The Collector logs the following internal events:
- Data dropping due to invalid data stops.
- A crash is detected, differentiated from a clean stop. Crash data is included
if available.
+
+## Use internal telemetry to monitor the Collector
+
+This section recommends best practices for monitoring the Collector using its
+own telemetry.
+
+### Critical monitoring
+
+#### Data loss
+
+Use the rate of `otelcol_processor_dropped_spans > 0` and
+`otelcol_processor_dropped_metric_points > 0` to detect data loss. Depending on
+your project's requirements, select a narrow time window before alerting begins
+to avoid notifications for small losses that are within the desired reliability
+range and not considered outages.
+
+### Secondary monitoring
+
+#### Queue length
+
+Most exporters provide a
+[queue or retry mechanism](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md)
+that is recommended for use in any production deployment of the Collector.
+
+The `otelcol_exporter_queue_capacity` metric indicates the capacity, in batches,
+of the retry queue. The `otelcol_exporter_queue_size` metric indicates the
+current size of the retry queue. Use these two metrics to check if the queue
+capacity can support your workload.
+
+Using the following three metrics, you can identify the number of spans, metric
+points, and log records that failed to reach the sending queue:
+
+- `otelcol_exporter_enqueue_failed_spans`
+- `otelcol_exporter_enqueue_failed_metric_points`
+- `otelcol_exporter_enqueue_failed_log_records`
+
+These failures could be caused by a queue filled with unsettled elements. You
+might need to decrease your sending rate or horizontally scale Collectors.
+
+The queue or retry mechanism also supports logging for monitoring. Check the
+logs for messages such as `Dropping data because sending_queue is full`.
+
+#### Receive failures
+
+Sustained rates of `otelcol_receiver_refused_spans` and
+`otelcol_receiver_refused_metric_points` indicate that too many errors were
+returned to clients. Depending on the deployment and the clients' resilience,
+this might indicate clients' data loss.
+
+Sustained rates of `otelcol_exporter_send_failed_spans` and
+`otelcol_exporter_send_failed_metric_points` indicate that the Collector is not
+able to export data as expected. These metrics do not inherently imply data loss
+since there could be retries. But a high rate of failures could indicate issues
+with the network or backend receiving the data.
+
+#### Data flow
+
+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.
diff --git a/content/en/docs/collector/troubleshooting.md b/content/en/docs/collector/troubleshooting.md
index 8278d00b678b..e48030b648fb 100644
--- a/content/en/docs/collector/troubleshooting.md
+++ b/content/en/docs/collector/troubleshooting.md
@@ -1,37 +1,135 @@
---
title: Troubleshooting
-description: Recommendations for troubleshooting the collector
+description: Recommendations for troubleshooting the Collector
weight: 25
+cSpell:ignore: pprof tracez zpages
---
-This page describes some options when troubleshooting the health or performance
-of the OpenTelemetry Collector. The Collector provides a variety of metrics,
-logs, and extensions for debugging issues.
+On this page, you can learn how to troubleshoot the health and performance of
+the OpenTelemetry Collector.
-## Internal telemetry
+## Troubleshooting tools
+
+The Collector provides a variety of metrics, logs, and extensions for debugging
+issues.
+
+### Internal telemetry
You can configure and use the Collector's own
[internal telemetry](/docs/collector/internal-telemetry/) to monitor its
performance.
-## Sending test data
+### Local exporters
+
+For certain types of issues, such as configuration verification and network
+debugging, you can send a small amount of test data to a Collector configured to
+output to local logs. Using a
+[local exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter#general-information),
+you can inspect the data being processed by the Collector.
+
+For live troubleshooting, consider using the
+[`debug` exporter](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/debugexporter/README.md),
+which can confirm that the Collector is receiving, processing, and exporting
+data. For example:
+
+```yaml
+receivers:
+ zipkin:
+exporters:
+ debug:
+service:
+ pipelines:
+ traces:
+ receivers: [zipkin]
+ processors: []
+ exporters: [debug]
+```
+
+To begin testing, generate a Zipkin payload. For example, you can create a file
+called `trace.json` that contains:
+
+```json
+[
+ {
+ "traceId": "5982fe77008310cc80f1da5e10147519",
+ "parentId": "90394f6bcffb5d13",
+ "id": "67fae42571535f60",
+ "kind": "SERVER",
+ "name": "/m/n/2.6.1",
+ "timestamp": 1516781775726000,
+ "duration": 26000,
+ "localEndpoint": {
+ "serviceName": "api"
+ },
+ "remoteEndpoint": {
+ "serviceName": "apip"
+ },
+ "tags": {
+ "data.http_response_code": "201"
+ }
+ }
+]
+```
+
+With the Collector running, send this payload to the Collector:
+
+```shell
+curl -X POST localhost:9411/api/v2/spans -H'Content-Type: application/json' -d @trace.json
+```
+
+You should see a log entry like the following:
-For certain types of issues, particularly verifying configuration and debugging
-network issues, it can be helpful to send a small amount of data to a collector
-configured to output to local logs. For details, see
-[Local exporters](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/troubleshooting.md#local-exporters).
+```shell
+2023-09-07T09:57:43.468-0700 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
+```
+
+You can also configure the `debug` exporter so the entire payload is printed:
+
+```yaml
+exporters:
+ debug:
+ verbosity: detailed
+```
+
+If you re-run the previous test with the modified configuration, the log output
+looks like this:
+
+```shell
+2023-09-07T09:57:12.820-0700 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
+2023-09-07T09:57:12.821-0700 info ResourceSpans #0
+Resource SchemaURL: https://opentelemetry.io/schemas/1.4.0
+Resource attributes:
+ -> service.name: Str(telemetrygen)
+ScopeSpans #0
+ScopeSpans SchemaURL:
+InstrumentationScope telemetrygen
+Span #0
+ Trace ID : 0c636f29e29816ea76e6a5b8cd6601cf
+ Parent ID : 1a08eba9395c5243
+ ID : 10cebe4b63d47cae
+ Name : okey-dokey
+ Kind : Internal
+ Start time : 2023-09-07 16:57:12.045933 +0000 UTC
+ End time : 2023-09-07 16:57:12.046058 +0000 UTC
+ Status code : Unset
+ Status message :
+Attributes:
+ -> span.kind: Str(server)
+ -> net.peer.ip: Str(1.2.3.4)
+ -> peer.service: Str(telemetrygen)
+```
-## Check available components in the Collector
+### Check Collector components
Use the following sub-command to list the available components in a Collector
distribution, including their stability levels. Please note that the output
-format may change across versions.
+format might change across versions.
-```sh
+```shell
otelcol components
```
-Sample output
+Sample output:
```yaml
buildinfo:
@@ -120,24 +218,144 @@ extensions:
extension: Beta
```
+### Extensions
+
+Here is a list of extensions you can enable for debugging the Collector.
+
+#### Performance Profiler (pprof)
+
+The
+[pprof extension](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/extension/pprofextension/README.md),
+which is available locally on port `1777`, allows you to profile the Collector
+as it runs. This is an advanced use-case that should not be needed in most
+circumstances.
+
+#### zPages
+
+The
+[zPages extension](https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/zpagesextension/README.md),
+which is exposed locally on port `55679`, can be used to inspect live data from
+the Collector's receivers and exporters.
+
+The TraceZ page, exposed at `/debug/tracez`, is useful for debugging trace
+operations, such as:
+
+- Latency issues. Find the slow parts of an application.
+- Deadlocks and instrumentation problems. Identify running spans that don't end.
+- Errors. Determine what types of errors are occurring and where they happen.
+
+Note that `zpages` might contain error logs that the Collector does not emit
+itself.
+
+For containerized environments, you might want to expose this port on a public
+interface instead of just locally. The `endpoint` can be configured using the
+`extensions` configuration section:
+
+```yaml
+extensions:
+ zpages:
+ endpoint: 0.0.0.0:55679
+```
+
## Checklist for debugging complex pipelines
It can be difficult to isolate problems when telemetry flows through multiple
-collectors and networks. For each "hop" of telemetry data through a collector or
-other component in your telemetry pipeline, it’s important to verify the
-following:
+Collectors and networks. For each "hop" of telemetry through a Collector or
+other component in your pipeline, it’s important to verify the following:
-- Are there error messages in the logs of the collector?
+- Are there error messages in the logs of the Collector?
- How is the telemetry being ingested into this component?
-- How is the telemetry being modified (i.e. sampling, redacting) by this
- component?
+- How is the telemetry being modified (for example, sampling or redacting) by
+ this component?
- How is the telemetry being exported from this component?
- What format is the telemetry in?
- How is the next hop configured?
- Are there any network policies that prevent data from getting in or out?
-### More
+## Common Collector issues
+
+This section covers how to resolve common Collector issues.
+
+### Collector is experiencing data issues
+
+The Collector and its components might experience data issues.
+
+#### Collector is dropping data
+
+The Collector might drop data for a variety of reasons, but the most common are:
+
+- The Collector is improperly sized, resulting in an inability to process and
+ export the data as fast as it is received.
+- The exporter destination is unavailable or accepting the data too slowly.
+
+To mitigate drops, configure the
+[`batch` processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/batchprocessor/README.md).
+In addition, it might be necessary to configure the
+[queued retry options](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/exporterhelper#configuration)
+on enabled exporters.
+
+#### Collector is not receiving data
+
+The Collector might not receive data for the following reasons:
+
+- A network configuration issue.
+- An incorrect receiver configuration.
+- An incorrect client configuration.
+- The receiver is defined in the `receivers` section but not enabled in any
+ `pipelines`.
+
+Check the Collector's
+[logs](/docs/collector/internal-telemetry/#configure-internal-logs) as well as
+[zPages](https://github.com/open-telemetry/opentelemetry-collector/blob/main/extension/zpagesextension/README.md)
+for potential issues.
+
+#### Collector is not processing data
+
+Most processing issues result from of a misunderstanding of how the processor
+works or a misconfiguration of the processor. For example:
+
+- The attributes processor works only for "tags" on spans. The span name is
+ handled by the span processor.
+- Processors for trace data (except tail sampling) work only on individual
+ spans.
+
+#### Collector is not exporting data
+
+The Collector might not export data for the following reasons:
+
+- A network configuration issue.
+- An incorrect exporter configuration.
+- The destination is unavailable.
+
+Check the Collector's
+[logs](/docs/collector/internal-telemetry/#configure-internal-logs) as well as
+[zPages](https://github.com/open-telemetry/opentelemetry-collector/blob/main/extension/zpagesextension/README.md)
+for potential issues.
+
+Exporting data often does not work because of a network configuration issue,
+such as a firewall, DNS, or proxy issue. Note that the Collector does have
+[proxy support](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter#proxy-support).
+
+### Collector is experiencing control issues
+
+The Collector might experience failed startups or unexpected exits or restarts.
+
+#### Collector exits or restarts
+
+The Collector might exit or restart due to:
+
+- Memory pressure from a missing or misconfigured
+ [`memory_limiter` processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md).
+- Improper sizing for load.
+- Improper configuration. For example, a queue size configured higher than
+ available memory.
+- Infrastructure resource limits. For example, Kubernetes.
+
+#### Collector fails to start in Windows Docker containers
-For detailed recommendations, including common problems, see
-[Troubleshooting](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/troubleshooting.md)
-from the Collector repository.
+With v0.90.1 and earlier, the Collector might fail to start in a Windows Docker
+container, producing the error message
+`The service process could not connect to the service controller`. In this case,
+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.
diff --git a/content/en/docs/concepts/instrumentation/libraries.md b/content/en/docs/concepts/instrumentation/libraries.md
index a2bd6b7cd3a6..8077817eb8f9 100644
--- a/content/en/docs/concepts/instrumentation/libraries.md
+++ b/content/en/docs/concepts/instrumentation/libraries.md
@@ -115,7 +115,7 @@ You may be rightfully concerned about adding new dependencies, here are some
considerations to help you decide how to minimize dependency hell:
- OpenTelemetry Trace API reached stability in early 2021, it follows
- [Semantic Versioning 2.0](/docs/specs/otel/versioning-and-stability) and we
+ [Semantic Versioning 2.0](/docs/specs/otel/versioning-and-stability/) and we
take API stability seriously.
- When taking dependency, use the earliest stable OpenTelemetry API (1.0.\*) and
avoid updating it unless you have to use new features.
diff --git a/content/en/docs/concepts/signals/logs.md b/content/en/docs/concepts/signals/logs.md
index c044175aa33d..e186218d0c62 100644
--- a/content/en/docs/concepts/signals/logs.md
+++ b/content/en/docs/concepts/signals/logs.md
@@ -95,7 +95,7 @@ Logs are a [stable](/docs/specs/otel/versioning-and-stability/#stable) signal in
the OpenTelemetry specification. For the individual language specific
implementations of the Logs API & SDK, the status is as follows:
-{{% logs-support-table %}}
+{{% signal-support-table "logs" %}}
## Specification
diff --git a/content/en/docs/concepts/signals/metrics.md b/content/en/docs/concepts/signals/metrics.md
index 4dc888a0f497..8e64ae9d86a7 100644
--- a/content/en/docs/concepts/signals/metrics.md
+++ b/content/en/docs/concepts/signals/metrics.md
@@ -114,7 +114,7 @@ Metrics are a [stable](/docs/specs/otel/versioning-and-stability/#stable) signal
in the OpenTelemetry specification. For the individual language specific
implementations of the Metrics API & SDK, the status is as follows:
-{{% metrics-support-table " " %}}
+{{% signal-support-table "metrics" %}}
## Specification
diff --git a/content/en/docs/contributing/_index.md b/content/en/docs/contributing/_index.md
index 5a16627ed0fa..5057845e9788 100644
--- a/content/en/docs/contributing/_index.md
+++ b/content/en/docs/contributing/_index.md
@@ -3,22 +3,8 @@ title: Contributing
description: Learn how to contribute to OpenTelemetry documentation.
aliases: [/docs/contribution-guidelines]
weight: 980
-cSpell:ignore: prepopulated spacewhite
---
-The following guide describes how to contribute to OpenTelemetry documentation.
-For guidance on how to contribute to the OpenTelemetry project in general, see
-the
-[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
-, which provides details on the Contributor License Agreement and the Code of
-Conduct. In extent, every language implementation, collector, and conventions
-[repository](https://github.com/open-telemetry/) has their own specific
-contributing guides.
-
-For documentation, you can open an issue about OpenTelemetry, or contribute a
-change with a pull request (PR) to the
-[`opentelemetry.io` GitHub repository](https://github.com/open-telemetry/opentelemetry.io).
-
OpenTelemetry documentation contributors:
- Improve existing content.
@@ -26,658 +12,18 @@ OpenTelemetry documentation contributors:
- Update the OpenTelemetry Registry.
- Improve the code that builds the site.
-## Requirements
-
-To contribute, you need to be familiar with the following techs and tools:
-
-- [git](https://git-scm.com/)
-- [GitHub](https://github.com/)
-- Markdown ([CommonMark](https://commonmark.org/))
-- YAML
-
-For technical details concerning how the documentation is built and tested
-locally, see the
-[CONTRIBUTING.md](https://github.com/open-telemetry/opentelemetry.io/blob/main/CONTRIBUTING.md)
-file.
-
-### Sign the CNCF CLA {#sign-the-cla}
-
-All OpenTelemetry contributors must read the
-[Contributor guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
-and
-[sign the Contributor License Agreement (CLA)](https://docs.linuxfoundation.org/lfx/easycla/contributors)
-.
-
-Pull requests from contributors who haven't signed the CLA fail the automated
-tests. The name and email you provide must match those found in your
-`git config`, and your git name and email must match those used for the CNCF
-CLA.
-
-## Contribute new content
-
-```mermaid
-flowchart LR
- subgraph first[How to contribute]
- direction TB
- T[ ] -.-
- B[Fork the repo in GitHub] --- C[Write docs in markdown and build site with Hugo]
- C --- D[Push source to the fork]
- D --- E[Open a pull request]
- E --- F[Sign the CNCF CLA]
- end
-
-classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
-classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
-classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
-class A,B,C,D,E,F,G,H grey
-class S,T spacewhite
-class first,second white
-```
-
-_Figure 1. Contributing new content._
-
-The previous figure illustrates how to contribute new documentation.
-
-To contribute new content pages or improve existing content pages, open a pull
-request (PR):
-
-- If your change is small, or you're unfamiliar with Git, read
- [Changes using GitHub](#changes-using-github) to learn how to edit a page.
-- If your changes are large, read [Work from a local fork](#fork-the-repo) to
- learn how to make changes locally on your computer.
-
-{{% alert title="Tip" %}}
-
-Turn your pull request into a draft to signal that the content still isn't ready
-for review. Maintainers may still comment or do high-level reviews, though they
-won't review the content in full until you remove the draft status.
-
-{{% /alert %}}
-
-### Changes using GitHub {#changes-using-github}
-
-If you're less experienced with Git workflows, here's an easier method of
-opening a pull request. Figure 2 outlines the steps and the details follow.
-
-```mermaid
-flowchart LR
-A([fa:fa-user New Contributor]) --- id1[(open-telemetry/opentelemetry.io GitHub)]
-subgraph tasks[Changes using GitHub]
-direction TB
- 0[ ] -.-
- 1[1. Edit this page] --> 2[2. Use GitHub markdown editor to make changes]
- 2 --> 3[3. fill in Propose file change]
-
-end
-subgraph tasks2[ ]
-direction TB
-4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request]
-6 --> 7[7. select Create pull request]
-end
-
-id1 --> tasks --> tasks2
-
-classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
-classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
-classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
-classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
-class A,1,2,3,4,5,6,7 grey
-class 0 spacewhite
-class tasks,tasks2 white
-class id1 k8s
-```
-
-_Figure 2. Steps for opening a PR using GitHub._
-
-1. On the page where you see the issue, select the **Edit this page** option in
- the right-hand side navigation panel.
-
-1. If you're not a member of the project, GitHub offers to create a fork of the
- repository. Select **Fork this repository**.
-
-1. Make your changes in the GitHub editor.
-
-1. Fill in the **Propose file change** form.
-
-1. Select **Propose file change**.
-
-1. Select **Create pull request**.
-
-1. The **Open a pull request** screen appears. Your description helps reviewers
- understand your change.
-
-1. Select **Create pull request**.
-
-Before merging a pull request, OpenTelemetry community members review and
-approve it.
-
-If a reviewer asks you to make changes:
-
-1. Go to the **Files changed** tab.
-1. Select the pencil (edit) icon on any files changed by the pull request.
-1. Make the changes requested. If there's a code suggestion, apply it.
-1. Commit the changes.
-
-When your review is complete, a reviewer merges your PR and your changes goes
-live a few minutes later.
-
-{{% alert title="Tip" %}}
-
-Comment `/fix:format` on your pull request to trigger an automated check for
-formatting issues.
-
-{{% /alert %}}
-
-### Work from a local fork {#fork-the-repo}
-
-If you're more experienced with Git, or if your changes are larger than a few
-lines, work from a local fork.
-
-Make sure you have
-[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed
-on your computer. You can also use a user interface for Git.
-
-Figure 3 shows the steps to follow when you work from a local fork. The details
-for each step follow.
-
-```mermaid
-flowchart LR
-1[Fork the open-telemetry/opentelemetry repository] --> 2[Create local clone and set upstream]
-subgraph changes[Your changes]
-direction TB
-S[ ] -.-
-3[Create a branch example: my_new_branch] --> 3a[Make changes using a text editor] --> 4["Preview your changes locally using Hugo (localhost:1313)"]
-end
-subgraph changes2[Commit / Push]
-direction TB
-T[ ] -.-
-5[Commit your changes] --> 6[Push commit to origin/my_new_branch]
-end
-
-2 --> changes --> changes2
-
-classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
-classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
-classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
-classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
-class 1,2,3,3a,4,5,6 grey
-class S,T spacewhite
-class changes,changes2 white
-```
-
-_Figure 3. Working from a local fork to make your changes._
-
-#### Fork the opentelemetry.io repository
-
-1. Navigate to the
- [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/)
- repository.
-1. Select **Fork**.
-
-#### Create a local clone and set the upstream
-
-1. In a terminal window, clone your fork and install the requirements:
-
- ```shell
- git clone git@github.com:/opentelemetry.io.git
- cd opentelemetry.io
- npm install
- ```
-
-1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream`
- remote:
-
- ```shell
- git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
- ```
-
-1. Confirm your `origin` and `upstream` repositories:
-
- ```shell
- git remote -v
- ```
-
- Output is similar to:
-
- ```none
- origin git@github.com:/opentelemetry.io.git (fetch)
- origin git@github.com:/opentelemetry.io.git (push)
- upstream https://github.com/open-telemetry/opentelemetry.io.git (fetch)
- upstream https://github.com/open-telemetry/opentelemetry.io.git (push)
- ```
-
-1. Fetch commits from your fork's `origin/main` and
- `open-telemetry/opentelemetry.io`'s `upstream/main`:
-
- ```shell
- git fetch origin
- git fetch upstream
- ```
-
- This makes sure your local repository is up to date before you start making
- changes. Push changes from upstream to origin regularly to keep your fork in
- sync with upstream.
-
-#### Create a branch
-
-1. Create a new branch. This example assumes the base branch is `upstream/main`:
-
- ```shell
- git checkout -b upstream/main
- ```
-
-1. Make your changes using a code or text editor.
-
-At any time, use the `git status` command to see what files you've changed.
-
-#### Commit your changes
-
-When you are ready to submit a pull request, commit your changes.
-
-1. In your local repository, check which files you need to commit:
-
- ```shell
- git status
- ```
-
- Output is similar to:
-
- ```none
- On branch
- Your branch is up to date with 'origin/'.
-
- Changes not staged for commit:
- (use "git add ..." to update what will be committed)
- (use "git checkout -- ..." to discard changes in working directory)
-
- modified: content/en/docs/file-you-are-editing.md
-
- no changes added to commit (use "git add" and/or "git commit -a")
- ```
-
-1. Add the files listed under **Changes not staged for commit** to the commit:
-
- ```shell
- git add
- ```
-
- Repeat this for each file.
-
-1. After adding all the files, create a commit:
-
- ```shell
- git commit -m "Your commit message"
- ```
-
-1. Push your local branch and its new commit to your remote fork:
-
- ```shell
- git push origin
- ```
-
-1. Once the changes are pushed, GitHub lets you know that you can create a PR.
-
-#### Open a pull request from your fork {#open-a-pr}
-
-Figure 4 shows the steps to open a PR from your fork to
-[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io).
-
-```mermaid
-flowchart LR
-subgraph first[ ]
-direction TB
-1[1. Go to opentelemetry.io repository] --> 2[2. Select New Pull Request]
-2 --> 3[3. Select compare across forks]
-3 --> 4[4. Select your fork from head repository drop-down menu]
-end
-subgraph second [ ]
-direction TB
-5[5. Select your branch from the compare drop-down menu] --> 6[6. Select Create Pull Request]
-6 --> 7[7. Add a description to your PR]
-7 --> 8[8. Select Create pull request]
-end
-
-first --> second
-
-classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
-classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
-class 1,2,3,4,5,6,7,8 grey
-class first,second white
-```
-
-_Figure 4. Steps to open a PR from your fork to_
-[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io).
-
-1. In a web browser, go to the
- [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io)
- repository.
-1. Select **New Pull Request**.
-1. Select **compare across forks**.
-1. From the **head repository** drop-down menu, select your fork.
-1. From the **compare** drop-down menu, select your branch.
-1. Select **Create Pull Request**.
-1. Add a description for your pull request:
-
- - **Title** (50 characters or less): Summarize the intent of the change.
- - **Description**: Describe the change in more detail.
-
- - If there is a related GitHub issue, include `Fixes #12345` or
- `Closes #12345` in the description so that GitHub's automation closes the
- mentioned issue after merging the PR. If there are other related PRs,
- link those as well.
- - If you want advice on something specific, include any questions you'd
- like reviewers to think about in your description.
+The following guides describe how to contribute to OpenTelemetry documentation.
-1. Select the **Create pull request** button.
-
-Your pull request is available in
-[Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls).
-
-After opening a PR, GitHub runs automated tests and tries to deploy a preview
-using [Netlify](https://www.netlify.com/).
-
-- If the Netlify build fails, select **Details** for more information.
-- If the Netlify build succeeds, select **Details** to open a staged version of
- the OpenTelemetry website with your changes applied. This is how reviewers
- check your changes.
-
-Other checks might also fail. See the
-[list of all PR checks](/docs/contributing/pr-checks).
-
-#### Fix content issues automatically
-
-Before submitting a change to the repository, run the following command and (i)
-address any reported issues, (ii) commit any files changed by the script:
-
-```sh
-npm run test-and-fix
-```
-
-To separately test and fix all issues with your files, run:
-
-```sh
-npm run test # Checks but does not update any files
-npm run fix:all # May update files
-```
-
-To list available NPM scripts, run `npm run`.
-
-#### Preview your changes locally {#preview-locally}
-
-Preview your changes locally before pushing them or opening a pull request. A
-preview lets you catch build errors or markdown formatting problems.
-
-To build and serve the site locally with Hugo, run the following command:
-
-```shell
-npm run serve
-```
-
-Navigate to `http://localhost:1313` in your web browser to see the local
-preview. Hugo watches for changes and rebuilds the site as needed.
-
-To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or
-close the terminal window.
-
-#### Site deploys and PR previews
-
-If you submit a PR, Netlify creates a [deploy preview][] so that you can review your
-changes. Once your PR is merged, Netlify deploys the updated site to the production
-server.
-
-> **Note**: PR previews include _draft pages_, but production builds do not.
-
-To see deploy logs and more, visit the project's [dashboard][] -- Netlify login
-required.
-
-#### PR guidelines
-
-Before a PR gets merged, it sometimes requires a few iterations of
-review-and-edit. To help us and yourself make this process as easy as possible,
-we ask that you adhere to the following:
-
-- If your PR isn't a quick fix, then **work from a fork**: Click the
- [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at the
- top of the repository and clone the fork locally. When you are ready, raise a
- PR with the upstream repository.
-- **Do not work from the `main`** branch of your fork, but create a PR-specific
- branch.
-- Ensure that maintainers are
- [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
-
-#### Changes from reviewers
-
-Sometimes reviewers commit to your pull request. Before making any other
-changes, fetch those commits.
-
-1. Fetch commits from your remote fork and rebase your working branch:
-
- ```shell
- git fetch origin
- git rebase origin/
- ```
-
-1. After rebasing, force-push new changes to your fork:
-
- ```shell
- git push --force-with-lease origin
- ```
-
-You can also solve merge conflicts from the GitHub UI.
-
-#### Merge conflicts and rebasing
-
-If another contributor commits changes to the same file in another PR, it can
-create a merge conflict. You must resolve all merge conflicts in your PR.
-
-1. Update your fork and rebase your local branch:
-
- ```shell
- git fetch origin
- git rebase origin/
- ```
-
- Then force-push the changes to your fork:
-
- ```shell
- git push --force-with-lease origin
- ```
-
-1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and
- rebase your branch:
-
- ```shell
- git fetch upstream
- git rebase upstream/main
- ```
-
-1. Inspect the results of the rebase:
-
- ```shell
- git status
- ```
-
- This results in a number of files marked as conflicted.
-
-1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`,
- and `===`. Resolve the conflict and delete the conflict marker.
-
- For more information, see
- [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented).
-
-1. Add the files to the changeset:
-
- ```shell
- git add
- ```
-
-1. Continue the rebase:
-
- ```shell
- git rebase --continue
- ```
-
-1. Repeat steps 2 to 5 as needed.
-
- After applying all commits, the `git status` command shows that the rebase is
- complete.
-
-1. Force-push the branch to your fork:
-
- ```shell
- git push --force-with-lease origin
- ```
-
- The pull request no longer shows any conflicts.
-
-#### Merge requirements
-
-Pull requests are merged when they comply with the following criteria:
-
-- All reviews by approvers, maintainers, technical committee members, or subject
- matter experts have the status "Approved".
-- No unresolved conversations.
-- Approved by at least one approver.
-- No failing PR checks.
-- PR branch is up-to-date with the base branch.
-
-> **Important**
->
-> Do not worry too much about failing PR checks. Community members will help you
-> to get them fixed, by either providing you with instructions how to fix them
-> or by fixing them on your behalf.
-
-## Open an issue
-
-If you notice an error or want to suggest improvements to existing content, open
-an issue.
-
-1. Click the **Create documentation issue** link on any document. This redirects
- you to a GitHub issue page prepopulated with some headers.
-2. Describe the issue or suggestion for improvement. Provide as many details as
- you can.
-3. Click **Submit new issue**.
-
-After submitting, check in on your issue occasionally or turn on GitHub
-notifications. It might take a few days until maintainers and approvers respond.
-Reviewers and other community members might ask questions before they can take
-action on your issue.
-
-### Suggesting new content or features
-
-If you have an idea for new content or a feature, but you aren't sure where it
-should go, you can still file an issue. You can also report bugs and security
-vulnerabilities.
-
-1. Go to
- [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and
- select **New issue** inside the **Issues** tab.
-
-1. Select the type of issue that best applies to your request or doubt.
-
-1. Fill out the template.
-
-1. Submit the issue.
-
-### How to file great issues
-
-Keep the following in mind when filing an issue:
-
-- Provide a clear issue description. Describe what specifically is missing, out
- of date, wrong, or needs improvement.
-- Explain the specific impact the issue has on users.
-- Limit the scope of a given issue to a reasonable unit of work. For problems
- with a large scope, break them down into smaller issues. For example, "Fix the
- security docs" is too broad, but "Add details to the 'Restricting network
- access' topic" is specific enough to be actionable.
-- Search the existing issues to see if there's anything related or similar to
- the new issue.
-- If the new issue relates to another issue or pull request, refer to it either
- by its full URL or by the issue or pull request number prefixed with a `#`
- character. For example, `Introduced by #987654`.
-- Follow the
- [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md).
- Respect your fellow contributors. For example, "The docs are terrible" is not
- helpful or polite feedback.
-
-## Announcement management
-
-An announcement is a _regular Hugo page_ contained under the `announcements`
-section of a locale. This means that we leverage Hugo's builtin handling of page
-dates (future or expired), internationalization, and more, to automatically show
-or hide banners depending on the build date, determine banner ordering, handle
-fall back to English banners, etc.
-
-> Announcements are currently used as banners only. We _might_ eventually
-> support slightly more general announcements as well.
-
-### Creating an announcement
-
-To add a new announcement, create an announcement markdown file under the
-`announcements` folder of your localization using the following command:
-
-```sh
-hugo new --kind announcement content/YOUR-LOCALE/announcements/announcement-file-name.md
-```
-
-Adjust according to your desired locale and file name. Add the announcement text
-as the body of the page.
-
-> For banners, the announcement body should be a short phrase.
-
-{{% alert title="For localizations" %}}
-
-If you are creating a **locale specific announcement override**, make sure that
-you use the **same filename** as the English language announcement.
-
-{{% /alert %}}
-
-### Announcement list
-
-Any given announcement will appear in a site build when the build date falls
-between the `date` and `expiryDate` fields of the announcement. When those
-fields are missing they are assumed to be "now" and "forever", respectively.
-
-Announcements will appear in the standard page order as determined using Hugo's
-[Regular pages](https://gohugo.io/methods/site/regularpages/) function. That is,
-the "lightest" announcements (by `weight`) will appear first; when weights are
-the same or unspecified, the most recent announcements (by `date`) will appear
-first, etc.
-
-So, if you want to force an announcement to the top, use a negative `weight` in
-the front matter.
-
-## Contribute to other repositories
-
-OpenTelemetry is an open source project, and we gladly accept new contributions
-and contributors. See the CONTRIBUTING.md file in each SIG repository for
-information on getting started.
-
-Individual SIGs may maintain documentation above and beyond what is offered
-here, but we strive for accurate general guidance on using the project from our
-main website.
-
-If you see text you'd like to improve, use GitHub to search all repositories in
-the OpenTelemetry organization. This can help you figure out where to submit
-your issue or PR. Each repository has its own processes and procedures. Before
-you file an issue or submit a PR, read that repository's `README.md`,
-`CONTRIBUTING.md`, and `code-of-conduct.md`, if they exist.
-
-Most repositories use issue and PR templates. Have a look through some open
-issues and PRs to get a feel for that team's processes. Make sure to fill out
-the templates with as much detail as possible when you file issues or PRs.
+For guidance on how to contribute to the OpenTelemetry project in general, see
+the
+[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
+, which provides details on the Contributor License Agreement and the Code of
+Conduct. Every language implementation, Collector, and conventions
+[repository](https://github.com/open-telemetry/) has its own specific
+contributing guides.
## Other ways to contribute
- Visit the [OpenTelemetry community site](/community/).
- Add your application to the [Registry](/ecosystem).
- Submit a [blog post or case study](/docs/contributing/blog/).
-
-[dashboard]: https://app.netlify.com/sites/opentelemetry/overview
-[deploy preview]:
- https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
-
-## Code of conduct
-
-OpenTelemetry follows the
-[CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
diff --git a/content/en/docs/contributing/announcements.md b/content/en/docs/contributing/announcements.md
new file mode 100644
index 000000000000..808ee7f902b7
--- /dev/null
+++ b/content/en/docs/contributing/announcements.md
@@ -0,0 +1,68 @@
+---
+title: Announcements
+description: Create announcements or banners for special events.
+weight: 50
+---
+
+An announcement is a _regular Hugo page_ contained under the `announcements`
+section of a locale. This means that we leverage Hugo's builtin handling of page
+dates (future or expired), internationalization, and more, to automatically show
+or hide banners depending on the build date, determine banner ordering, handle
+fall back to English banners, etc.
+
+> Announcements are currently used as banners only. We _might_ eventually
+> support slightly more general announcements as well.
+
+### Creating an announcement
+
+To add a new announcement, create an announcement markdown file under the
+`announcements` folder of your localization using the following command:
+
+```sh
+hugo new --kind announcement content/YOUR-LOCALE/announcements/announcement-file-name.md
+```
+
+Adjust according to your desired locale and file name. Add the announcement text
+as the body of the page.
+
+> For banners, the announcement body should be a short phrase.
+
+{{% alert title="For localizations" %}}
+
+If you are creating a **locale specific announcement override**, make sure that
+you use the **same filename** as the English language announcement.
+
+{{% /alert %}}
+
+### Announcement list
+
+Any given announcement will appear in a site build when the build date falls
+between the `date` and `expiryDate` fields of the announcement. When those
+fields are missing they are assumed to be "now" and "forever", respectively.
+
+Announcements will appear in the standard page order as determined using Hugo's
+[Regular pages](https://gohugo.io/methods/site/regularpages/) function. That is,
+the "lightest" announcements (by `weight`) will appear first; when weights are
+the same or unspecified, the most recent announcements (by `date`) will appear
+first, etc.
+
+So, if you want to force an announcement to the top, use a negative `weight` in
+the front matter.
+
+If you find a bug or a problem with the content of this repository, or you would
+like to request an enhancement, [create an issue][new-issue].
+
+If you discover a security issue, read the
+[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy)
+before opening an issue.
+
+Before reporting a new issue, make sure that the issue was not already reported
+or fixed by searching through our
+[issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).
+
+When creating a new issue, include a short, meaningful title and a clear
+description. Add as much relevant information as you can, and, if possible, a
+test case.
+
+[new-issue]:
+ https://github.com/open-telemetry/opentelemetry.io/issues/new/choose
diff --git a/content/en/docs/contributing/development.md b/content/en/docs/contributing/development.md
new file mode 100644
index 000000000000..67ccb8e36391
--- /dev/null
+++ b/content/en/docs/contributing/development.md
@@ -0,0 +1,210 @@
+---
+title: Development
+description:
+ Learn how to set up a development environment for the opentelemetry.io site.
+weight: 60
+cSpell:ignore: chalin
+---
+
+The following instructions explain how to set up a development environment for
+the website.
+
+## Cloud-IDE setup
+
+These instructions are for [Gitpod.io][], adjust as needed for your favorite
+cloud IDE:
+
+1. Fork this repository. For help, see [Fork a repository][fork].
+2. From [gitpod.io/workspaces][], create a new workspace (do this only once) or
+ open an existing workspace over your fork. You can also visit a link of the
+ form:
+ .
+
+ > **Note**: If you have the necessary permissions to work from this
+ > repository, or just want to look around, open
+ > .
+
+Gitpod automatically installs the repo-specific packages for you.
+
+You're now ready to [build](#build), [serve](#serve) or make updates to the
+website files.
+
+## Local setup
+
+1. [Fork][] and then [clone][] this repository.
+2. Go to the repository directory.
+3. Install or upgrade to the [**active LTS** release][nodejs-rel] of Node.js.
+ We recommend using [nvm][] to manage your Node installation. Under Linux,
+ run the following command, which will install and upgrade to the version
+ specified in the .nvmrc file:
+
+ ```sh
+ nvm install
+ ```
+
+ To [install under Windows][nodejs-win], use [nvm-windows][]:
+
+ ```cmd
+ > nvm install lts && nvm use lts
+ ```
+
+4. Get npm packages and other prerequisites:
+
+ ```sh
+ npm install
+ ```
+
+You're now ready to [build](#build), [serve](#serve) or make updates to the
+website files.
+
+### Build
+
+To build the site run:
+
+```sh
+npm run build
+```
+
+The generated site files are under `public`.
+
+### Serve
+
+To serve the site run:
+
+```sh
+npm run serve
+```
+
+The site is served at [localhost:1313][].
+
+If you need to test [Netlify] redirects, use the following command and visit the
+site at [localhost:8888][]:
+
+```sh
+npm run serve:netlify
+```
+
+The serve command serves files from memory, not from disk.
+
+If you see an error like `too many open files` or `pipe failed` under macOS, you
+might need to increase the file descriptor limit. See
+[Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109).
+
+### Content and submodules
+
+The website is built from the following content:
+
+- Files under `content/`, `static/`, etc. per [Hugo][] defaults.
+- Mount points, defined in [hugo.yaml][] under `mounts`. Mounts are either
+ directly from git submodules under [content-modules][], or preprocessed
+ content from `content-modules` (placed under `tmp/`), and no where else.
+
+[hugo.yaml]:
+ https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml
+[content-modules]:
+ https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules
+
+### Submodule changes
+
+If you change any content inside of a [content-modules][] submodule, then you
+need to first submit a PR (containing the submodule changes) to the submodule's
+repository. Only after the submodule PR has been accepted, can you update the
+submodule and have the changes appear in this website.
+
+It's easiest to manage your `content-modules` changes by working with the
+repository that the corresponding submodule is linked to, rather than inside the
+submodule itself.
+
+Expert contributors can work directly in the submodule. You are then able to
+directly build and serve your (submodule) changes. By default, the CI scripts
+get submodules on every invocation. To prevent this behavior while you work
+within a submodule, set the environment variable `GET=no`. You also need to run
+`git fetch --unshallow` the submodule before you can submit a PR. Alternatively,
+set `DEPTH=100` and re-fetch submodules.
+
+## Approver and maintainer practices
+
+This last section includes guidelines and some common practices used by
+approvers and maintainers while doing code reviews:
+
+- PRs with changes to documentation co-owned by a SIG (collector, demo,
+ language-specific...) should aim for two approvals: one by a docs approver and
+ one by a SIG approver:
+ - Doc approver label such PRs with `sig:` and tag the SIG `-approvers`
+ group on that PR
+ - After a doc approver has reviewed and approved the PR, they can add the
+ label
+ [`sig-approval-missing`](https://github.com/open-telemetry/opentelemetry.io/labels/sig-approval-missing).
+ This signals to the SIG that they need to handle the PR
+ - If no SIG approval is given within a certain grace period (two weeks in
+ general, but may be less in urgent cases), docs maintainer may use their own
+ judgement to merge that PR
+- PRs created by bots can be merged by the following practice:
+ - PRs that auto-update versions in the registry can be fixed, approved and
+ merged immediately
+ - PRs that auto-update the versions of SDKs, zero-code instrumentations or the
+ collector can be approved and merged except the corresponding SIG signals
+ that merging should be postponed
+ - PRs that auto-update the version of any specification often require updates
+ to scripts for the CI checks to pass. In that case often
+ [@chalin](https://github.com/chalin/) will handle that PR. Otherwise those
+ PRs can as well be approved and merged except the corresponding SIG signals
+ that merging should be postponed.
+- PRs with changes to translations should aim for two approvals: one by a docs
+ approver and one by a translation approver. Similar practices apply as
+ suggested for the co-owned PRs.
+- If the PR branch is `out-of-date with the base branch`, they do not need to be
+ updated continuously: every update triggers all the PR CI checks to be run!
+ It's often enough to update them before merging.
+- A PR by non-maintainers should **never** update git sub modules. This happens
+ by accident from time to time. Let the PR author know that they should not
+ worry about it, we will fix this before merging, but in the future they should
+ make sure that they work from an up-to-date fork.
+- If the contributor is having trouble signing the CLA or used the wrong email
+ by mistake in one of their commits, ask them to fix the issue or rebase the
+ pull request. Worst case scenario, close and re-open the PR to trigger a new
+ CLA check.
+- Words unknown to cspell should be added to the cspell ignore list per page by
+ PR authors. Only approvers and maintainers will add commonly used terms to the
+ global list.
+- Approvers and maintainers have different work schedules and circumstances.
+ That's why all communication is assumed to be asynchronously and they should
+ not feel obligated to reply outside of their normal schedule.
+- When an approver or maintainer won't be available to contribute for an
+ extended period of time (more than a few days or a week) or won't be available
+ in that period of time, they should communicate this using the
+ [#otel-comms](https://cloud-native.slack.com/archives/C02UN96HZH6) channel and
+ updating the GitHub status.
+- Approver and maintainer adhere to the
+ [OTel Code of Conduct](https://github.com/open-telemetry/community/?tab=coc-ov-file#opentelemetry-community-code-of-conduct)
+ and are friendly and helpful towards contributors. In the case of a conflict,
+ misunderstanding or any other kind of situation that makes an
+ approver/maintainer feel uncomfortable they can step back from a conversation,
+ issue or PR and ask another approver/maintainer to step in.
+
+The following workflow can be applied by maintainers to merge PRs:
+
+- Make sure that a PR has all approvals and all CI checks pass
+- If the branch is out-of-date, rebase update it via the GitHub UI.
+- The update will trigger all CI checks to run again, wait for them to pass or
+ execute a script like the following to make it happen in the background:
+
+ ```shell
+ export PR=; gh pr checks ${PR} --watch && gh pr merge ${PR} --squash
+ ```
+
+[clone]:
+ https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
+[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+[gitpod.io]: https://gitpod.io
+[gitpod.io/workspaces]: https://gitpod.io/workspaces
+[hugo]: https://gohugo.io
+[localhost:1313]: http://localhost:1313
+[localhost:8888]: http://localhost:8888
+[netlify]: https://netlify.com
+[nodejs-rel]: https://nodejs.org/en/about/previous-releases
+[nodejs-win]:
+ https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows
+[nvm]:
+ https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating
+[nvm-windows]: https://github.com/coreybutler/nvm-windows
diff --git a/content/en/docs/contributing/issues.md b/content/en/docs/contributing/issues.md
new file mode 100644
index 000000000000..4aeca18c85e9
--- /dev/null
+++ b/content/en/docs/contributing/issues.md
@@ -0,0 +1,57 @@
+---
+title: Reporting an issue
+description: How to report a bug, a security issue, or a potential improvement.
+weight: 50
+cSpell:ignore: prepopulated
+---
+
+If you notice an error or want to suggest improvements to existing content, open
+an issue.
+
+1. Click the **Create documentation issue** link on any document. This redirects
+ you to a GitHub issue page prepopulated with some headers.
+2. Describe the issue or suggestion for improvement. Provide as many details as
+ you can.
+3. Click **Submit new issue**.
+
+After submitting, check in on your issue occasionally or turn on GitHub
+notifications. It might take a few days until maintainers and approvers respond.
+Reviewers and other community members might ask questions before they can take
+action on your issue.
+
+## Suggesting new content or features
+
+If you have an idea for new content or a feature, but you aren't sure where it
+should go, you can still file an issue. You can also report bugs and security
+vulnerabilities.
+
+1. Go to
+ [GitHub](https://github.com/open-telemetry/opentelemetry.io/issues/new/) and
+ select **New issue** inside the **Issues** tab.
+
+1. Select the type of issue that best applies to your request or doubt.
+
+1. Fill out the template.
+
+1. Submit the issue.
+
+### How to file great issues
+
+Keep the following in mind when filing an issue:
+
+- Provide a clear issue description. Describe what specifically is missing, out
+ of date, wrong, or needs improvement.
+- Explain the specific impact the issue has on users.
+- Limit the scope of a given issue to a reasonable unit of work. For problems
+ with a large scope, break them down into smaller issues. For example, "Fix the
+ security docs" is too broad, but "Add details to the 'Restricting network
+ access' topic" is specific enough to be actionable.
+- Search the existing issues to see if there's anything related or similar to
+ the new issue.
+- If the new issue relates to another issue or pull request, refer to it either
+ by its full URL or by the issue or pull request number prefixed with a `#`
+ character. For example, `Introduced by #987654`.
+- Follow the
+ [Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md).
+ Respect your fellow contributors. For example, "The docs are terrible" is not
+ helpful or polite feedback.
diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md
index b5c07db3c6d4..edcc9a62be6d 100644
--- a/content/en/docs/contributing/localization.md
+++ b/content/en/docs/contributing/localization.md
@@ -3,7 +3,7 @@ title: Site localization
description:
Guidance on creating and maintaining site page in non-English localizations.
linkTitle: Localization
-weight: 20
+weight: 25
---
{{% pageinfo color="warning" %}}
@@ -17,6 +17,28 @@ English is the default language, with US English as the default (implicit) local
A growing number of other localizations are supported, as can be seen from the languages
dropdown menu in the top nav.
+## Translation tips
+
+When you translate page content, follow this guidance:
+
+- To ensure that heading anchor targets are uniform across localizations, when
+ translating headings:
+ - If the heading has an explicit ID (which is of the form `{ #some-id }` and
+ comes after the heading text), then preserve the given ID
+ - Otherwise, include a heading ID corresponding to the original English
+ heading text.
+- For link references that are local paths, preserve the path _as is_.
+
+{{% alert title="Note" %}}
+
+This repository has a custom render-link hook that Hugo uses to convert
+**absolute link paths to documentation pages** that are of the form
+`/docs/some-page`, to be locale specific, by prefixing the path with page
+language code when rendering the link. For example, the previous sample path
+would become `/ja/docs/some-page` when rendered from a Japanese page.
+
+{{% /alert %}}
+
## Keeping track of localized page drift {#track-changes}
One of the main challenges of maintaining localized pages, is identifying when
diff --git a/content/en/docs/contributing/new-content.md b/content/en/docs/contributing/new-content.md
new file mode 100644
index 000000000000..7ccb57284f95
--- /dev/null
+++ b/content/en/docs/contributing/new-content.md
@@ -0,0 +1,503 @@
+---
+title: Add new content
+description: Learn how to add new content using GitHub UI or a local fork.
+weight: 2
+---
+
+To contribute new content pages or improve existing content pages, open a pull
+request (PR):
+
+- If your change is small, or you're unfamiliar with Git, read
+ [Changes using GitHub](#changes-using-github) to learn how to edit a page.
+- If your changes are large, read [Work from a local fork](#fork-the-repo) to
+ learn how to make changes locally on your computer.
+
+{{% alert title="Tip" %}}
+
+Turn your pull request into a draft to signal that the content still isn't ready
+for review. Maintainers may still comment or do high-level reviews, though they
+won't review the content in full until you remove the draft status.
+
+{{% /alert %}}
+
+The following figure illustrates how to contribute new documentation.
+
+```mermaid
+flowchart LR
+ subgraph first[How to contribute]
+ direction TB
+ T[ ] -.-
+ B[Fork the repo in GitHub] --- C[Write docs in markdown and build site with Hugo]
+ C --- D[Push source to the fork]
+ D --- E[Open a pull request]
+ E --- F[Sign the CNCF CLA]
+ end
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,B,C,D,E,F,G,H grey
+class S,T spacewhite
+class first,second white
+```
+
+_Figure 1. Contributing new content._
+
+## Changes using GitHub {#changes-using-github}
+
+If you're less experienced with Git workflows, here's an easier method of
+opening a pull request. Figure 2 outlines the steps and the details follow.
+
+```mermaid
+flowchart LR
+A([fa:fa-user New Contributor]) --- id1[(open-telemetry/opentelemetry.io GitHub)]
+subgraph tasks[Changes using GitHub]
+direction TB
+ 0[ ] -.-
+ 1[1. Edit this page] --> 2[2. Use GitHub markdown editor to make changes]
+ 2 --> 3[3. fill in Propose file change]
+
+end
+subgraph tasks2[ ]
+direction TB
+4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request]
+6 --> 7[7. select Create pull request]
+end
+
+id1 --> tasks --> tasks2
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,1,2,3,4,5,6,7 grey
+class 0 spacewhite
+class tasks,tasks2 white
+class id1 k8s
+```
+
+_Figure 2. Steps for opening a PR using GitHub._
+
+1. On the page where you see the issue, select the **Edit this page** option in
+ the right-hand side navigation panel.
+
+1. If you're not a member of the project, GitHub offers to create a fork of the
+ repository. Select **Fork this repository**.
+
+1. Make your changes in the GitHub editor.
+
+1. Fill in the **Propose file change** form.
+
+1. Select **Propose file change**.
+
+1. Select **Create pull request**.
+
+1. The **Open a pull request** screen appears. Your description helps reviewers
+ understand your change.
+
+1. Select **Create pull request**.
+
+Before merging a pull request, OpenTelemetry community members review and
+approve it.
+
+If a reviewer asks you to make changes:
+
+1. Go to the **Files changed** tab.
+1. Select the pencil (edit) icon on any files changed by the pull request.
+1. Make the changes requested. If there's a code suggestion, apply it.
+1. Commit the changes.
+
+When your review is complete, a reviewer merges your PR and your changes goes
+live a few minutes later.
+
+{{% alert title="Tip" %}}
+
+Comment `/fix:format` on your pull request to trigger an automated check for
+formatting issues.
+
+{{% /alert %}}
+
+## Work from a local fork {#fork-the-repo}
+
+If you're more experienced with Git, or if your changes are larger than a few
+lines, work from a local fork.
+
+Make sure you have
+[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed
+on your computer. You can also use a user interface for Git.
+
+Figure 3 shows the steps to follow when you work from a local fork. The details
+for each step follow.
+
+```mermaid
+flowchart LR
+1[Fork the open-telemetry/opentelemetry repository] --> 2[Create local clone and set upstream]
+subgraph changes[Your changes]
+direction TB
+S[ ] -.-
+3[Create a branch example: my_new_branch] --> 3a[Make changes using a text editor] --> 4["Preview your changes locally using Hugo (localhost:1313)"]
+end
+subgraph changes2[Commit / Push]
+direction TB
+T[ ] -.-
+5[Commit your changes] --> 6[Push commit to origin/my_new_branch]
+end
+
+2 --> changes --> changes2
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class 1,2,3,3a,4,5,6 grey
+class S,T spacewhite
+class changes,changes2 white
+```
+
+_Figure 3. Working from a local fork to make your changes._
+
+### Fork the opentelemetry.io repository
+
+1. Navigate to the
+ [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io/)
+ repository.
+1. Select **Fork**.
+
+### Create a local clone and set the upstream
+
+1. In a terminal window, clone your fork and install the requirements:
+
+ ```shell
+ git clone git@github.com:/opentelemetry.io.git
+ cd opentelemetry.io
+ npm install
+ ```
+
+1. Set the `open-telemetry/opentelemetry.io` repository as the `upstream`
+ remote:
+
+ ```shell
+ git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
+ ```
+
+1. Confirm your `origin` and `upstream` repositories:
+
+ ```shell
+ git remote -v
+ ```
+
+ Output is similar to:
+
+ ```none
+ origin git@github.com:/opentelemetry.io.git (fetch)
+ origin git@github.com:/opentelemetry.io.git (push)
+ upstream https://github.com/open-telemetry/opentelemetry.io.git (fetch)
+ upstream https://github.com/open-telemetry/opentelemetry.io.git (push)
+ ```
+
+1. Fetch commits from your fork's `origin/main` and
+ `open-telemetry/opentelemetry.io`'s `upstream/main`:
+
+ ```shell
+ git fetch origin
+ git fetch upstream
+ ```
+
+ This makes sure your local repository is up to date before you start making
+ changes. Push changes from upstream to origin regularly to keep your fork in
+ sync with upstream.
+
+### Create a branch
+
+1. Create a new branch. This example assumes the base branch is `upstream/main`:
+
+ ```shell
+ git checkout -b upstream/main
+ ```
+
+1. Make your changes using a code or text editor.
+
+At any time, use the `git status` command to see what files you've changed.
+
+### Commit your changes
+
+When you are ready to submit a pull request, commit your changes.
+
+1. In your local repository, check which files you need to commit:
+
+ ```shell
+ git status
+ ```
+
+ Output is similar to:
+
+ ```none
+ On branch
+ Your branch is up to date with 'origin/'.
+
+ Changes not staged for commit:
+ (use "git add ..." to update what will be committed)
+ (use "git checkout -- ..." to discard changes in working directory)
+
+ modified: content/en/docs/file-you-are-editing.md
+
+ no changes added to commit (use "git add" and/or "git commit -a")
+ ```
+
+1. Add the files listed under **Changes not staged for commit** to the commit:
+
+ ```shell
+ git add
+ ```
+
+ Repeat this for each file.
+
+1. After adding all the files, create a commit:
+
+ ```shell
+ git commit -m "Your commit message"
+ ```
+
+1. Push your local branch and its new commit to your remote fork:
+
+ ```shell
+ git push origin
+ ```
+
+1. Once the changes are pushed, GitHub lets you know that you can create a PR.
+
+### Open a pull request from your fork {#open-a-pr}
+
+Figure 4 shows the steps to open a PR from your fork to
+[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io).
+
+```mermaid
+flowchart LR
+subgraph first[ ]
+direction TB
+1[1. Go to opentelemetry.io repository] --> 2[2. Select New Pull Request]
+2 --> 3[3. Select compare across forks]
+3 --> 4[4. Select your fork from head repository drop-down menu]
+end
+subgraph second [ ]
+direction TB
+5[5. Select your branch from the compare drop-down menu] --> 6[6. Select Create Pull Request]
+6 --> 7[7. Add a description to your PR]
+7 --> 8[8. Select Create pull request]
+end
+
+first --> second
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+class 1,2,3,4,5,6,7,8 grey
+class first,second white
+```
+
+_Figure 4. Steps to open a PR from your fork to_
+[opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io).
+
+1. In a web browser, go to the
+ [`opentelemetry.io`](https://github.com/open-telemetry/opentelemetry.io)
+ repository.
+1. Select **New Pull Request**.
+1. Select **compare across forks**.
+1. From the **head repository** drop-down menu, select your fork.
+1. From the **compare** drop-down menu, select your branch.
+1. Select **Create Pull Request**.
+1. Add a description for your pull request:
+
+ - **Title** (50 characters or less): Summarize the intent of the change.
+ - **Description**: Describe the change in more detail.
+
+ - If there is a related GitHub issue, include `Fixes #12345` or
+ `Closes #12345` in the description so that GitHub's automation closes the
+ mentioned issue after merging the PR. If there are other related PRs,
+ link those as well.
+ - If you want advice on something specific, include any questions you'd
+ like reviewers to think about in your description.
+
+1. Select the **Create pull request** button.
+
+Your pull request is available in
+[Pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls).
+
+After opening a PR, GitHub runs automated tests and tries to deploy a preview
+using [Netlify](https://www.netlify.com/).
+
+- If the Netlify build fails, select **Details** for more information.
+- If the Netlify build succeeds, select **Details** to open a staged version of
+ the OpenTelemetry website with your changes applied. This is how reviewers
+ check your changes.
+
+Other checks might also fail. See the
+[list of all PR checks](/docs/contributing/pr-checks).
+
+### Fix content issues automatically
+
+Before submitting a change to the repository, run the following command and (i)
+address any reported issues, (ii) commit any files changed by the script:
+
+```sh
+npm run test-and-fix
+```
+
+To separately test and fix all issues with your files, run:
+
+```sh
+npm run test # Checks but does not update any files
+npm run fix:all # May update files
+```
+
+To list available NPM scripts, run `npm run`. See
+[PR checks](/docs/contributing/pr-checks) for more information on pull request
+checks and how to fix errors automatically.
+
+### Preview your changes locally {#preview-locally}
+
+Preview your changes locally before pushing them or opening a pull request. A
+preview lets you catch build errors or markdown formatting problems.
+
+To build and serve the site locally with Hugo, run the following command:
+
+```shell
+npm run serve
+```
+
+Navigate to `http://localhost:1313` in your web browser to see the local
+preview. Hugo watches for changes and rebuilds the site as needed.
+
+To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`, or
+close the terminal window.
+
+### Site deploys and PR previews
+
+If you submit a PR, Netlify creates a [deploy preview][] so that you can review your
+changes. Once your PR is merged, Netlify deploys the updated site to the production
+server.
+
+> **Note**: PR previews include _draft pages_, but production builds do not.
+
+To see deploy logs and more, visit the project's [dashboard][] -- Netlify login
+required.
+
+### PR guidelines
+
+Before a PR gets merged, it sometimes requires a few iterations of
+review-and-edit. To help us and yourself make this process as easy as possible,
+we ask that you adhere to the following:
+
+- If your PR isn't a quick fix, then **work from a fork**: Click the
+ [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at the
+ top of the repository and clone the fork locally. When you are ready, raise a
+ PR with the upstream repository.
+- **Do not work from the `main`** branch of your fork, but create a PR-specific
+ branch.
+- Ensure that maintainers are
+ [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
+
+### Changes from reviewers
+
+Sometimes reviewers commit to your pull request. Before making any other
+changes, fetch those commits.
+
+1. Fetch commits from your remote fork and rebase your working branch:
+
+ ```shell
+ git fetch origin
+ git rebase origin/
+ ```
+
+1. After rebasing, force-push new changes to your fork:
+
+ ```shell
+ git push --force-with-lease origin
+ ```
+
+You can also solve merge conflicts from the GitHub UI.
+
+### Merge conflicts and rebasing
+
+If another contributor commits changes to the same file in another PR, it can
+create a merge conflict. You must resolve all merge conflicts in your PR.
+
+1. Update your fork and rebase your local branch:
+
+ ```shell
+ git fetch origin
+ git rebase origin/
+ ```
+
+ Then force-push the changes to your fork:
+
+ ```shell
+ git push --force-with-lease origin
+ ```
+
+1. Fetch changes from `open-telemetry/opentelemetry.io`'s `upstream/main` and
+ rebase your branch:
+
+ ```shell
+ git fetch upstream
+ git rebase upstream/main
+ ```
+
+1. Inspect the results of the rebase:
+
+ ```shell
+ git status
+ ```
+
+ This results in a number of files marked as conflicted.
+
+1. Open each conflicted file and look for the conflict markers: `>>>`, `<<<`,
+ and `===`. Resolve the conflict and delete the conflict marker.
+
+ For more information, see
+ [How conflicts are presented](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented).
+
+1. Add the files to the changeset:
+
+ ```shell
+ git add
+ ```
+
+1. Continue the rebase:
+
+ ```shell
+ git rebase --continue
+ ```
+
+1. Repeat steps 2 to 5 as needed.
+
+ After applying all commits, the `git status` command shows that the rebase is
+ complete.
+
+1. Force-push the branch to your fork:
+
+ ```shell
+ git push --force-with-lease origin
+ ```
+
+ The pull request no longer shows any conflicts.
+
+### Merge requirements
+
+Pull requests are merged when they comply with the following criteria:
+
+- All reviews by approvers, maintainers, technical committee members, or subject
+ matter experts have the status "Approved".
+- No unresolved conversations.
+- Approved by at least one approver.
+- No failing PR checks.
+- PR branch is up-to-date with the base branch.
+
+> **Important**
+>
+> Do not worry too much about failing PR checks. Community members will help you
+> to get them fixed, by either providing you with instructions how to fix them
+> or by fixing them on your behalf.
+
+[dashboard]: https://app.netlify.com/sites/opentelemetry/overview
+[deploy preview]:
+ https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
diff --git a/content/en/docs/contributing/pr-checks.md b/content/en/docs/contributing/pr-checks.md
index 64b1e2d9ae0a..d59ce9abcb47 100644
--- a/content/en/docs/contributing/pr-checks.md
+++ b/content/en/docs/contributing/pr-checks.md
@@ -19,7 +19,7 @@ a set of checks are executed. The PR checks verify that...
{{% alert title="Note" color="primary" %}}
If any of the PR checks fails, please try to
-[fix content issues automatically](/docs/contributing/#fix-content-issues-automatically)
+[fix content issues automatically](/docs/contributing/new-content/#fix-content-issues-automatically)
first by running `npm run fix:all` on your machine.
Additionally, you can comment `/fix:all` on your Pull Request. This will make
@@ -34,7 +34,7 @@ can recover from a failed state.
## Easy CLA
This check fails if you haven't
-[signed the CLA](/docs/contributing/#sign-the-cla).
+[signed the CLA](/docs/contributing/requirements/#sign-the-cla).
## Netlify deployment
diff --git a/content/en/docs/contributing/requirements.md b/content/en/docs/contributing/requirements.md
new file mode 100644
index 000000000000..cd90ca36161f
--- /dev/null
+++ b/content/en/docs/contributing/requirements.md
@@ -0,0 +1,33 @@
+---
+title: Requirements
+description:
+ To contribute, you need to be familiar with the following techs and tools.
+weight: 1
+---
+
+To contribute, you need to be familiar with the following techs and tools:
+
+- [git](https://git-scm.com/)
+- [GitHub](https://github.com/)
+- Markdown ([CommonMark](https://commonmark.org/))
+- YAML
+
+For technical details concerning how the documentation is built and tested
+locally, see [Development](/docs/contributing/development).
+
+## Sign the CNCF CLA {#sign-the-cla}
+
+All OpenTelemetry contributors must read the
+[Contributor guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
+and
+[sign the Contributor License Agreement (CLA)](https://docs.linuxfoundation.org/lfx/easycla/contributors).
+
+Pull requests from contributors who haven't signed the CLA fail the automated
+tests. The name and email you provide must match those found in your
+`git config`, and your git name and email must match those used for the CNCF
+CLA.
+
+## Code of conduct
+
+OpenTelemetry follows the
+[CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
diff --git a/content/en/docs/contributing/style-guide.md b/content/en/docs/contributing/style-guide.md
index 3d3341733982..7438b97bc8dc 100644
--- a/content/en/docs/contributing/style-guide.md
+++ b/content/en/docs/contributing/style-guide.md
@@ -1,7 +1,8 @@
---
title: Documentation style guide
+description: Terminology and style when writing OpenTelemetry docs.
linkTitle: Style guide
-weight: 10
+weight: 20
cSpell:ignore: open-telemetry postgre style-guide textlintrc
---
@@ -22,7 +23,7 @@ before submitting a
(PR), run `npm run fix:all` on your local machine and commit the changes.
If you run into errors or [failed PR checks](/docs/contributing/pr-checks), read
-about our style guide below and what you can do to fix certain common issues.
+about our style guide and learn what you can do to fix certain common issues.
{{% /alert %}}
@@ -36,7 +37,7 @@ the site.
| --- | --- |
| OpenTelemetry | OpenTelemetry should always be capitalized. Don't use Open-Telemetry. |
| OTel | OTel is the accepted short form of OpenTelemetry. Don't use OTEL. |
-| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. |
+| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. Write "The Collector" or "The Opentelemetry Collector" if you're starting a sentence. Write "the Collector" or "the OpenTelemetry Collector" in the middle or end of a sentence. Use just "Collector" if you are using Collector as an adjective (for example, "Collector configuration").|
| OTEP | OpenTelemetry Enhancement Proposal. Write "OTEPs" as plural form. Don't write "OTep" or "otep". |
| OpAMP | Open Agent Management Protocol. Don't write "OPAMP" or "opamp" in descriptions or instructions. |
@@ -107,11 +108,11 @@ run `npm run fix:dict`.
## File format
To enforce a certain standard on how files are structured, all files should be
-formatted by [prettier](https://prettier.io). Run `npm fix:format` before
+formatted by [prettier](https://prettier.io). Run `npm run fix:format` before
submitting a PR, or run it afterwards and push an additional commit.
## File names
All file names should be in
[kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). Run
-`npm fix:filenames` to automatically rename your files.
+`npm run fix:filenames` to automatically rename your files.
diff --git a/content/en/docs/demo/services/payment.md b/content/en/docs/demo/services/payment.md
index 3fbf0170c16d..5c018ceaa3d5 100644
--- a/content/en/docs/demo/services/payment.md
+++ b/content/en/docs/demo/services/payment.md
@@ -87,7 +87,7 @@ You can then use `opentelemetry.js` to start your app. This can be done in the
`ENTRYPOINT` command for the service's `Dockerfile`.
```dockerfile
-ENTRYPOINT [ "node", "./opentelemetry.js" ]
+ENTRYPOINT [ "node", "--require", "./opentelemetry.js", "./index.js" ]
```
## Traces
diff --git a/content/en/docs/languages/java/instrumentation.md b/content/en/docs/languages/java/instrumentation.md
index 146f5e474c7e..7050d917311e 100644
--- a/content/en/docs/languages/java/instrumentation.md
+++ b/content/en/docs/languages/java/instrumentation.md
@@ -571,7 +571,7 @@ If you followed the instructions to [initialize the SDK](#initialize-the-sdk)
above, you have a `TracerProvider` setup for you already. You can continue with
[acquiring a tracer](#acquiring-a-tracer).
-### Acquiring a Tracer
+### Acquiring a tracer
To do [Tracing](/docs/concepts/signals/traces/) you'll need to acquire a
[`Tracer`](/docs/concepts/signals/traces/#tracer).
@@ -676,6 +676,53 @@ Tracer tracer = GlobalOpenTelemetry.getTracer("instrumentation-scope-name", "ins
Note that you can't force end users to configure the global, so this is the most
brittle option for library instrumentation.
+### Acquiring a tracer in Java agent
+
+If you are using the [Java agent], you can acquire a `Tracer` from the global OpenTelemetry
+instance:
+
+```java
+import io.opentelemetry.api.GlobalOpenTelemetry;
+
+Tracer tracer = GlobalOpenTelemetry.getTracer("application");
+```
+
+If you are using Spring Boot, you can add the following bean to your
+`@SpringBootApplication` class - to acquire a `Tracer` as in the
+[Spring Boot starter](#acquiring-a-tracer-in-spring-boot-starter) section below:
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.GlobalOpenTelemetry;
+
+@Configuration
+public class OpenTelemetryConfig {
+ @Bean
+ public OpenTelemetry openTelemetry() {
+ return GlobalOpenTelemetry.get();
+ }
+}
+```
+
+### Acquiring a tracer in Spring Boot starter
+
+If you are using the [Spring Boot starter], you can acquire a `Tracer` from the
+autowired OpenTelemetry instance:
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+
+@Controller
+public class MyController {
+ private final Tracer tracer;
+
+ public MyController(OpenTelemetry openTelemetry) {
+ this.tracer = openTelemetry.getTracer("application");
+ }
+}
+```
+
### Create Spans
Now that you have [tracers](/docs/concepts/signals/traces/#tracer) initialized,
@@ -1194,7 +1241,7 @@ OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
.build();
```
-### Acquiring a Meter
+### Acquiring a meter
Anywhere in your application where you have manually instrumented code you can
call `opentelemetry.meterBuilder(instrumentationScopeName)` to get or create a
@@ -1216,6 +1263,55 @@ Now that you have [meters](/docs/concepts/signals/metrics/#meter) initialized.
you can create
[metric instruments](/docs/concepts/signals/metrics/#metric-instruments).
+### Acquiring a meter in Java agent
+
+If you are using the [Java agent], you can acquire a `Meter` from the global OpenTelemetry
+instance:
+
+```java
+import io.opentelemetry.api.GlobalOpenTelemetry;
+
+Meter meter = GlobalOpenTelemetry.getMeter("application");
+```
+
+If you are using Spring Boot, you can add the following bean to your
+`@SpringBootApplication` class - to acquire a `Meter` as in the
+[Spring Boot starter](#acquiring-a-meter-in-spring-boot-starter) section below:
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.GlobalOpenTelemetry;
+
+@Configuration
+public class OpenTelemetryConfig {
+ @Bean
+ public OpenTelemetry openTelemetry() {
+ return GlobalOpenTelemetry.get();
+ }
+}
+```
+
+### Acquiring a meter in Spring Boot starter
+
+If you are using the [Spring Boot starter], you can acquire a `Meter` from the
+autowired OpenTelemetry instance:
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.metrics.Meter;
+
+@Controller
+public class MyController {
+ private final Meter meter;
+
+ public MyController(OpenTelemetry openTelemetry) {
+ this.meter = openTelemetry.getMeter("application");
+ }
+}
+```
+
+a
+
### Using Counters
Counters can be used to measure non-negative, increasing values.
@@ -1857,3 +1953,5 @@ io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extensio
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/ParentBasedSampler.java
[traceidratiobased]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/TraceIdRatioBasedSampler.java
+[Java agent]: /docs/zero-code/java/agent/
+[Spring Boot starter]: /docs/zero-code/java/spring-boot-starter/
diff --git a/content/en/docs/languages/python/_index.md b/content/en/docs/languages/python/_index.md
index e373c4998a5d..08ed02503454 100644
--- a/content/en/docs/languages/python/_index.md
+++ b/content/en/docs/languages/python/_index.md
@@ -11,7 +11,7 @@ weight: 22
## Version support
-OpenTelemetry-Python supports Python 3.6 and higher.
+OpenTelemetry-Python supports Python 3.8 and higher.
## Installation
diff --git a/content/en/docs/zero-code/java/_index.md b/content/en/docs/zero-code/java/_index.md
index aa82346ebeed..c1d0290b3072 100644
--- a/content/en/docs/zero-code/java/_index.md
+++ b/content/en/docs/zero-code/java/_index.md
@@ -7,7 +7,7 @@ aliases:
cascade:
vers:
instrumentation: 2.4.0
- otel: 1.38.0
+ otel: 1.39.0
---
Zero-code instrumentation with Java uses a Java agent JAR or Spring Boot
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/getting-started.md b/content/en/docs/zero-code/java/spring-boot-starter/getting-started.md
index eba5b9332a8b..8d2da55ea72d 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/getting-started.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/getting-started.md
@@ -13,7 +13,7 @@ application. For the pros and cons, see [Java zero-code instrumentation](..).
### Compatibility
-The OpenTelemetry Spring Boot starter works with Spring Boot 2.6+ and 3.0+, and
+The OpenTelemetry Spring Boot starter works with Spring Boot 2.6+ and 3.1+, and
Spring Boot native image applications. The
[opentelemetry-java-examples/spring-native](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native)
repository contains an example of a Spring Boot Native image application
diff --git a/content/ja/docs/getting-started/_index.md b/content/ja/docs/getting-started/_index.md
new file mode 100644
index 000000000000..ae2467dea262
--- /dev/null
+++ b/content/ja/docs/getting-started/_index.md
@@ -0,0 +1,29 @@
+---
+title: Getting Started（入門）
+description: あなたの役割に応じてOpenTelemetryを始めてみましょう。
+no_list: true
+weight: 160
+default_lang_commit: e7a6289
+---
+
+まずは役割[^1]を選択してください。
+
+