open-telemetry
/
opentelemetry.io
mirror of https://github.com/open-telemetry/opentelemetry.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

CI: run markdown linter on all pages + fixes (#3032)

This commit is contained in:
Patrice Chalin 2023-07-13 20:51:36 -04:00 committed by GitHub
parent c9beb59b2c
commit bdca9aa2ec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
48 changed files with 643 additions and 347 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/check-links.yml vendored
View File

@ -1,4 +1,4 @@
name: Check links and refcache # cSpell:ignore refcache
name: Check links and refcache
on:
pull_request:

24
.github/workflows/check-text.yml vendored
View File

@ -1,11 +1,11 @@
name: Check text linter rules # cSpell:ignore refcache startswith
name: Check linter rules
on:
pull_request:
jobs:
check-formatting:
name: Check text linter rules
text-linter:
name: TEXT linter
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
@ -14,3 +14,21 @@ jobs:
jq 'del(.dependencies) | .devDependencies |= with_entries( select(.key | startswith("textlint")))' package.json > package2.json && mv package2.json package.json
- run: npm install --ignore-scripts
- run: npm run check:text
markdown-linter:
name: MARKDOWN linter
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Create and use reduced-dependencies package.json
run: |
mkdir -p tmp
jq '.devDependencies |= with_entries(
select(.key | test("gulp|markdown|through|require|yargs"))
)
| del(.dependencies)' \
package.json > tmp/package-min.json
cp tmp/package-min.json package.json
- run: npm install --ignore-scripts
- run: npm run check:markdown

29
.markdownlint.json Normal file
View File

@ -0,0 +1,29 @@
{
"no-inline-html": false,
"no-emphasis-as-header": false,
"no-trailing-punctuation": false,
"fenced-code-language": false,
"comment": "Disables rules that may conflict with Prettier",
"blanks-around-fences": false,
"blanks-around-headings": false,
"blanks-around-lists": false,
"code-fence-style": false,
"emphasis-style": false,
"heading-start-left": false,
"hr-style": false,
"line-length": false,
"list-indent": false,
"list-marker-space": false,
"no-blanks-blockquote": false,
"no-hard-tabs": false,
"no-missing-space-atx": false,
"no-missing-space-closed-atx": false,
"no-multiple-blanks": false,
"no-multiple-space-atx": false,
"no-multiple-space-blockquote": false,
"no-multiple-space-closed-atx": false,
"no-trailing-spaces": false,
"ol-prefix": false,
"strong-style": false,
"ul-indent": false
}

4
CONTRIBUTING.md
View File

@ -74,8 +74,8 @@ 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][]:
If you need to test [Netlify] redirects, use the following command, and visit
the site at [localhost:8888][]:
```sh
npm run serve:netlify

2
README.md
View File

@ -13,7 +13,7 @@ missing [let us know][]!
Read on to learn about other ways on how you can help.
## Adding a project to the OpenTelemetry Registry
## Adding a project to the OpenTelemetry [Registry]
For details, see [Adding to the registry][].

12
content/en/blog/2022/instrument-nginx/index.md
View File

@ -167,14 +167,14 @@ startup.
Get everything up and running[^1]:
```console
$ docker compose up
```sh
docker compose up
```
In another shell, create some traffic:
```console
$ curl localhost:8080
```sh
curl localhost:8080
```
In your browser open [localhost:16686][] and search for traces from
@ -331,8 +331,8 @@ You should now have the following files in your top level directory:
With everything in place, you can now start the demo environment[^1]:
```console
$ docker compose up
```sh
docker compose up
```
Within a few moments you should have five docker containers up and running:

21
content/en/blog/2022/k8s-otel-expose/index.md
View File

@ -3,9 +3,9 @@ title: Exposing a Collector for cross cluster communication
linkTitle: Exposing a Collector
date: 2022-09-08
author: '[Benedikt Bongartz](https://github.com/frzifus)'
spelling: cSpell:ignore k8sattributes k8sattributesprocessor K8sattributes
spelling: cSpell:ignore k8sattributes k8sattributesprocessor K8sattributes
spelling: cSpell:ignore K8sprocessor Benedikt Bongartz Keycloak k8sprocessor
spelling: cSpell:ignore dXNlci0xOjEyMzQK basicauth htpasswd llczt
spelling: cSpell:ignore dXNlci0xOjEyMzQK basicauth htpasswd llczt
spelling: cSpell:ignore oidc rolebinding letsencrypt frzifus
---
@ -103,17 +103,16 @@ transmitted traces are stored in a
Interfaces and behavior may change in the future. Therefore, the versions used
in this setup are mentioned in brackets.
- A Kubernetes[v1.23.3] cluster with a public address with
[ingress-nginx-controller](https://docs.nginx.com/nginx-ingress-controller/)[v1.2.1]
installed.
- A Kubernetes[v1.23.3] edge cluster to create a test cluster. Using
- A Kubernetes [v1.23.3] cluster with a public address with
[ingress-nginx-controller](https://docs.nginx.com/nginx-ingress-controller/)
[v1.2.1] installed.
- A Kubernetes [v1.23.3] edge cluster to create a test cluster. Using
[Kind](https://kind.sigs.k8s.io/) is recommended.
- Installed [OpenTelemetry Operator](/docs/collector/getting-started)[v0.58.0]
- Installed [OpenTelemetry Operator](/docs/collector/getting-started) [v0.58.0]
on both ends.
- Installed
[Jaeger Operator](https://www.jaegertracing.io/docs/1.37/operator/)[v1.37.0]
on your public cluster.
- Installed [cert-manager](https://cert-manager.io/)[v1.9.1] on your public
- Installed [Jaeger Operator](https://www.jaegertracing.io/docs/1.37/operator/)
[v1.37.0] on your public cluster.
- Installed [cert-manager](https://cert-manager.io/) [v1.9.1] on your public
cluster.
## Remote cluster configuration

4
content/en/blog/2023/end-user-discussions-02.md
View File

@ -169,7 +169,7 @@ landing on a particular page which can be tracked with a counter.
The community also discussed these important points:
#### Auto-discovery of sources to collect telemetry data
### Auto-discovery of sources to collect telemetry data
**Q:** Can OTel Collector automatically discover known sources and collect
telemetry from them?
@ -189,7 +189,7 @@ Using
users should be able to detect and report Kubernetes pod, port, and node
endpoints via the Kubernetes API.
#### Hosting pattern suggestion of the OTel Collector within Azure
### Hosting pattern suggestion of the OTel Collector within Azure
**Q:** Are there any suggestions for hosting pattern of the Collector within
Azure to collect telemetry from Azure App Services and Azure functions?

2
content/en/blog/2023/end-user-discussions-04.md
View File

@ -65,7 +65,7 @@ that you incur less cost.
## Other Important discussion points
#### Maturity model for OpenTelemetry
### Maturity model for OpenTelemetry
**Q:** Is there some literature available around understanding steps to reach a
certain maturity level in adopting OTel in your organization? For example, I

2
content/en/blog/2023/otel-in-focus-02.md
View File

@ -20,6 +20,8 @@ channel.
Here are the latest updates from our core repositories.
<!-- markdownlint-disable heading-increment -->
##### [Specification](/docs/specs/otel/)
[v1.18](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.18.0)

4
content/en/blog/2023/otel-in-focus-03.md
View File

@ -3,7 +3,7 @@ title: OpenTelemetry in Focus, March 2023
linkTitle: OTel in Focus 2023/03
date: 2023-03-31
author: '[Austin Parker](https://github.com/austinlparker)'
spelling: cSpell:ignore spanmetricsconnector spanmetricsprocessor
spelling: cSpell:ignore spanmetricsconnector spanmetricsprocessor
spelling: cSpell:ignore Jodd Ktor Webflux
---
@ -22,6 +22,8 @@ channel.
Here are the latest updates from our core repositories.
<!-- markdownlint-disable heading-increment -->
##### [Specification](/docs/specs/otel/)
[Version 1.19](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.19.0)

2
content/en/blog/2023/otel-in-focus-04.md
View File

@ -21,6 +21,8 @@ channel.
Here are the latest updates from some of our core repositories.
<!-- markdownlint-disable heading-increment -->
##### [Specification](/docs/specs/otel/)
[Version 1.20](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.20.0)

2
content/en/blog/2023/otel-in-focus-05.md
View File

@ -19,6 +19,8 @@ channel.
Here are the latest updates from some of our core repositories.
<!-- markdownlint-disable heading-increment -->
##### [Specification](/docs/specs/otel/)
[Version 1.21](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.21.0)

4
content/en/blog/2023/otel-in-focus-06.md
View File

@ -3,7 +3,7 @@ title: OpenTelemetry in Focus, June 2023
linkTitle: OTel in Focus 2023/06
date: 2023-07-01
author: '[Austin Parker](https://github.com/austinlparker)'
spelling: cSpell:ignore scraperhelper Skywalking autoconfigure Logback Quarkus
spelling: cSpell:ignore scraperhelper Skywalking autoconfigure Logback Quarkus
spelling: cSpell:ignore Ktor Farfetch Dyrmishi Inet
---
@ -20,6 +20,8 @@ channel.
Here are the latest updates from some of our core repositories.
<!-- markdownlint-disable heading-increment -->
##### [Specification](/docs/specs/otel/)
[Version 1.22](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.22.0)

2
content/en/community/marketing-guidelines.md
View File

@ -86,7 +86,7 @@ concerns.
Here is how we handle such circumstances:
1. Whomever notices the relevant public (marketing) content should write an
email to cncf-opentelemetry-governance@lists.cncf.io and include an
email to <cncf-opentelemetry-governance@lists.cncf.io> and include an
explanation of why the content is problematic, ideally referencing the
[relevant guidelines above](#goals-and-guidelines).
1. The OTel Governance Committee (GC) will discuss the case during its next

485
content/en/docs/collector/benchmarks.md
View File

@ -3,75 +3,74 @@ title: Benchmarks
weight: 99
---
<style>
<style>
main {
margin: 8px;
width: 100%;
display: flex;
flex-direction: column;
}
main {
margin: 8px;
width: 100%;
display: flex;
flex-direction: column;
}
button {
color: #fff;
background-color: #3298dc;
border-color: transparent;
cursor: pointer;
text-align: center;
}
button {
color: #fff;
background-color: #3298dc;
border-color: transparent;
cursor: pointer;
text-align: center;
}
button:hover {
background-color: #2793da;
flex: none;
}
button:hover {
background-color: #2793da;
flex: none;
}
.spacer {
flex: auto;
}
.spacer {
flex: auto;
}
.small {
font-size: 0.75rem;
}
.small {
font-size: 0.75rem;
}
footer {
margin-top: 16px;
display: flex;
align-items: center;
}
footer {
margin-top: 16px;
display: flex;
align-items: center;
}
.benchmark-set {
margin: 8px 0;
width: 100%;
display: flex;
flex-direction: column;
}
.benchmark-set {
margin: 8px 0;
width: 100%;
display: flex;
flex-direction: column;
}
.benchmark-title {
font-size: 3rem;
font-weight: 600;
word-break: break-word;
text-align: center;
}
.benchmark-title {
font-size: 3rem;
font-weight: 600;
word-break: break-word;
text-align: center;
}
.benchmark-graphs {
display: flex;
flex-direction: column;
justify-content: space-around;
align-items: center;
flex-wrap: wrap;
width: 100%;
}
.benchmark-graphs {
display: flex;
flex-direction: column;
justify-content: space-around;
align-items: center;
flex-wrap: wrap;
width: 100%;
}
.benchmark-chart {
max-width: 1000px;
}
.benchmark-chart {
max-width: 1000px;
}
div.container {
max-width: 1012px;
margin-right: auto;
margin-left: auto;
}
</style>
div.container {
max-width: 1012px;
margin-right: auto;
margin-left: auto;
}
</style>
The OpenTelemetry Collector runs load tests on every commit to the
[opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/)
@ -80,214 +79,216 @@ configuration options per test and send traffic through the collector.
Additional information regarding the testing environment can be found in the
[repository](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/testbed#opentelemetry-collector-testbed).
A subset of the results are shown below, the full results are available
[here](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/).
A subset of the results are shown below. For all the results, see
[Collector Benchmarks](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/).
<div class="container">
<main id="main"></main>
</div>
<!-- markdownlint-disable -->
<footer>
<button id="dl-button">Download data as JSON</button>
<div class="spacer"></div>
<div class="small">Powered by <a rel="noopener"
href="https://github.com/marketplace/actions/continuous-benchmark">github-action-benchmark</a></div>
</footer>
<div class="container">
<main id="main"></main>
</div>
<script src="https://cdn.jsdelivr.net/npm/chart.js@2.9.2/dist/Chart.min.js"></script>
<script src="https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/data.js"></script>
<script id="main-script">
'use strict';
(function () {
const COLORS = [
"#48aaf9",
"#8a3ef2",
"#78eeda",
"#d78000",
"#1248b3",
"#97dbfc",
"#006174",
"#00b6b6",
"#854200",
"#f3c8ad",
"#410472",
];
<footer>
<button id="dl-button">Download data as JSON</button>
<div class="spacer"></div>
<div class="small">Powered by <a rel="noopener"
href="https://github.com/marketplace/actions/continuous-benchmark">github-action-benchmark</a></div>
</footer>
function init() {
function collectBenchesPerTestCase(entries) {
const byGroup = new Map();
const commitIds = [];
for (const entry of entries) {
const { commit, date, tool, benches } = entry;
const commitId = commit.id.slice(0, 7);
commitIds.push(commitId);
for (const bench of benches) {
const result = { commit, date, tool, bench };
if (!bench.extra.includes("10kDPS") && !bench.extra.includes("10kSPS")){
continue
}
const extraParts = bench.extra.split("/");
let benchmarkName = extraParts[0] + " - " + bench.name;
let byName = byGroup.get(benchmarkName);
if (byName === undefined) {
byName = new Map();
byGroup.set(benchmarkName, byName);
}
let extraName = bench.extra
if (extraParts.length > 1) {
extraName = extraParts[1].split(" - ")[0]
}
let byCommitId = byName.get(extraName);
if (byCommitId === undefined) {
byCommitId = new Map();
byCommitId.set(commitId, result)
byName.set(extraName, byCommitId);
} else {
byCommitId.set(commitId, result);
}
<script src="https://cdn.jsdelivr.net/npm/chart.js@2.9.2/dist/Chart.min.js"></script>
<script src="https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/data.js"></script>
<script id="main-script">
'use strict';
(function () {
const COLORS = [
"#48aaf9",
"#8a3ef2",
"#78eeda",
"#d78000",
"#1248b3",
"#97dbfc",
"#006174",
"#00b6b6",
"#854200",
"#f3c8ad",
"#410472",
];
function init() {
function collectBenchesPerTestCase(entries) {
const byGroup = new Map();
const commitIds = [];
for (const entry of entries) {
const { commit, date, tool, benches } = entry;
const commitId = commit.id.slice(0, 7);
commitIds.push(commitId);
for (const bench of benches) {
const result = { commit, date, tool, bench };
if (!bench.extra.includes("10kDPS") && !bench.extra.includes("10kSPS")){
continue
}
const extraParts = bench.extra.split("/");
let benchmarkName = extraParts[0] + " - " + bench.name;
let byName = byGroup.get(benchmarkName);
if (byName === undefined) {
byName = new Map();
byGroup.set(benchmarkName, byName);
}
let extraName = bench.extra
if (extraParts.length > 1) {
extraName = extraParts[1].split(" - ")[0]
}
let byCommitId = byName.get(extraName);
if (byCommitId === undefined) {
byCommitId = new Map();
byCommitId.set(commitId, result)
byName.set(extraName, byCommitId);
} else {
byCommitId.set(commitId, result);
}
}
return {
commitIds,
byGroup
};
}
const data = window.BENCHMARK_DATA;
// Render footer
document.getElementById('dl-button').onclick = () => {
const dataUrl = 'data:,' + JSON.stringify(data, null, 2);
const a = document.createElement('a');
a.href = dataUrl;
a.download = 'benchmark_data.json';
a.click();
return {
commitIds,
byGroup
};
// Prepare data points for charts
return Object.keys(data.entries).map(name => ({
name,
dataSet: collectBenchesPerTestCase(data.entries[name]),
}));
}
function renderAllChars(dataSets) {
const data = window.BENCHMARK_DATA;
function renderGraph(parent, name, commitIds, byName) {
const chartTitle = document.createElement('h3');
chartTitle.textContent = name;
parent.append(chartTitle);
// Render footer
document.getElementById('dl-button').onclick = () => {
const dataUrl = 'data:,' + JSON.stringify(data, null, 2);
const a = document.createElement('a');
a.href = dataUrl;
a.download = 'benchmark_data.json';
a.click();
};
const canvas = document.createElement('canvas');
canvas.className = 'benchmark-chart';
parent.appendChild(canvas);
// Prepare data points for charts
return Object.keys(data.entries).map(name => ({
name,
dataSet: collectBenchesPerTestCase(data.entries[name]),
}));
}
const results = [];
for (const [name, byCommitId] of byName.entries()) {
results.push({
name,
dataset: commitIds.map(commitId => byCommitId.get(commitId) ?? null)
});
}
results.sort((a, b) => a.name.localeCompare(b.name));
function renderAllChars(dataSets) {
const data = {
labels: commitIds,
datasets: results.map(({ name, dataset }, index) => {
const color = COLORS[index % COLORS.length];
function renderGraph(parent, name, commitIds, byName) {
const chartTitle = document.createElement('h3');
chartTitle.textContent = name;
parent.append(chartTitle);
return {
label: name,
data: dataset.map(d => d?.bench.value ?? null),
fill: false,
borderColor: color,
backgroundColor: color,
};
}),
};
const canvas = document.createElement('canvas');
canvas.className = 'benchmark-chart';
parent.appendChild(canvas);
const options = {
scales: {
xAxes: [
{
scaleLabel: {
display: true,
labelString: 'commit',
},
}
],
yAxes: [
{
scaleLabel: {
display: true,
labelString: results?.[0]?.dataset.find(d => d !== null)?.bench.unit ?? '',
},
ticks: {
beginAtZero: true,
}
}
],
},
tooltips: {
callbacks: {
afterTitle: items => {
const { datasetIndex, index } = items[0];
const data = results[datasetIndex].dataset[index];
return '\n' + data.commit.message + '\n\n' + data.commit.timestamp + ' committed by @' + data.commit.author.username + '\n';
},
label: item => {
const { datasetIndex, index, value } = item;
const { name, dataset } = results[datasetIndex];
const { range, unit } = dataset[index].bench;
let label = `${name}: ${value}`;
label += unit;
if (range) {
label += ' (' + range + ')';
}
return label;
},
}
},
legend: {
display: true,
position: "right"
}
};
new Chart(canvas, {
type: 'line',
data,
options,
const results = [];
for (const [name, byCommitId] of byName.entries()) {
results.push({
name,
dataset: commitIds.map(commitId => byCommitId.get(commitId) ?? null)
});
}
results.sort((a, b) => a.name.localeCompare(b.name));
function renderBenchSet(name, benchSet, main) {
const setElem = document.createElement('div');
setElem.className = 'benchmark-set';
main.appendChild(setElem);
const data = {
labels: commitIds,
datasets: results.map(({ name, dataset }, index) => {
const color = COLORS[index % COLORS.length];
const graphsElem = document.createElement('div');
graphsElem.className = 'benchmark-graphs';
setElem.appendChild(graphsElem);
return {
label: name,
data: dataset.map(d => d?.bench.value ?? null),
fill: false,
borderColor: color,
backgroundColor: color,
};
}),
};
const { commitIds, byGroup } = benchSet;
const groups = [];
for (const [name, byName] of byGroup.entries()) {
groups.push({ name, byName });
const options = {
scales: {
xAxes: [
{
scaleLabel: {
display: true,
labelString: 'commit',
},
}
],
yAxes: [
{
scaleLabel: {
display: true,
labelString: results?.[0]?.dataset.find(d => d !== null)?.bench.unit ?? '',
},
ticks: {
beginAtZero: true,
}
}
],
},
tooltips: {
callbacks: {
afterTitle: items => {
const { datasetIndex, index } = items[0];
const data = results[datasetIndex].dataset[index];
return '\n' + data.commit.message + '\n\n' + data.commit.timestamp + ' committed by @' + data.commit.author.username + '\n';
},
label: item => {
const { datasetIndex, index, value } = item;
const { name, dataset } = results[datasetIndex];
const { range, unit } = dataset[index].bench;
let label = `${name}: ${value}`;
label += unit;
if (range) {
label += ' (' + range + ')';
}
return label;
},
}
},
legend: {
display: true,
position: "right"
}
groups.sort((a, b) => a.name.localeCompare(b.name));
};
for (const { name, byName } of groups) {
renderGraph(graphsElem, name, commitIds, byName);
}
new Chart(canvas, {
type: 'line',
data,
options,
});
}
function renderBenchSet(name, benchSet, main) {
const setElem = document.createElement('div');
setElem.className = 'benchmark-set';
main.appendChild(setElem);
const graphsElem = document.createElement('div');
graphsElem.className = 'benchmark-graphs';
setElem.appendChild(graphsElem);
const { commitIds, byGroup } = benchSet;
const groups = [];
for (const [name, byName] of byGroup.entries()) {
groups.push({ name, byName });
}
groups.sort((a, b) => a.name.localeCompare(b.name));
const main = document.getElementById('main');
for (const { name, dataSet } of dataSets) {
renderBenchSet(name, dataSet, main);
for (const { name, byName } of groups) {
renderGraph(graphsElem, name, commitIds, byName);
}
}
renderAllChars(init()); // Start
})();
</script>
const main = document.getElementById('main');
for (const { name, dataSet } of dataSets) {
renderBenchSet(name, dataSet, main);
}
}
renderAllChars(init()); // Start
})();
</script>

2
content/en/docs/collector/configuration.md
View File

@ -7,6 +7,8 @@ spelling: cSpell:ignore prometheusremotewrite prodevent spanmetrics servicegraph
spelling: cSpell:ignore oidc cfssl genkey initca cfssljson gencert
---
<!-- markdownlint-disable link-fragments -->
Familiarity with the following pages is assumed:
- [Data collection concepts][dcc] in order to understand the repositories

2
content/en/docs/collector/deployment/agent.md
View File

@ -36,6 +36,7 @@ export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318
The collector serving at `collector.example.com:4318` would then be configured
like so:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=yaml >}}
{{< tab Traces >}}
@ -104,6 +105,7 @@ service:
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
If you want to try it out for yourself, you can have a look at the end-to-end
[Java][java-otlp-example] or [Python][py-otlp-example] examples.

14
content/en/docs/collector/getting-started.md
View File

@ -30,6 +30,7 @@ Pull a docker image and run the collector in a container. Replace
`{{% param collectorVersion %}}` with the version of the Collector you wish to
run.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab DockerHub >}}
@ -43,10 +44,12 @@ docker run ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
To load your custom configuration `config.yaml` from your current working
directory, mount that file as a volume:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab DockerHub >}}
@ -58,6 +61,7 @@ docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml ghcr.io/open-t
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Docker Compose
@ -115,6 +119,7 @@ To get started on alpine systems run the following replacing
`v{{% param collectorVersion %}}` with the version of the Collector you wish to
run.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab AMD64 >}}
@ -139,6 +144,7 @@ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_386.apk
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### DEB Installation
@ -146,6 +152,7 @@ To get started on Debian systems run the following replacing
`v{{% param collectorVersion %}}` with the version of the Collector you wish to
run and `amd64` with the appropriate architecture.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab AMD64 >}}
@ -170,6 +177,7 @@ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_386.deb
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### RPM Installation
@ -177,6 +185,7 @@ To get started on Red Hat systems run the following replacing
`v{{% param collectorVersion %}}` with the version of the Collector you wish to
run and `x86_64` with the appropriate architecture.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab AMD64 >}}
@ -201,6 +210,7 @@ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_386.rpm
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Manual Installation
@ -208,6 +218,7 @@ Linux [releases][] are available for various architectures. It's possible to
download the archive containing the binary and install it on your machine
manually:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab AMD64 >}}
@ -231,6 +242,7 @@ tar -xvf otelcol_{{% param collectorVersion %}}_linux_ppc64le.tar.gz
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Automatic Service Configuration
@ -261,6 +273,7 @@ MacOS [releases][] are available for Intel- & ARM-based systems. They are
packaged as gzipped tarballs (`.tar.gz`) and will need to be unpacked with a
tool that supports this compression format:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab Intel >}}
@ -274,6 +287,7 @@ tar -xvf otelcol_{{% param collectorVersion %}}_darwin_arm64.tar.gz
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Every Collector release includes an `otelcol` executable that you can run after
unpacking.

4
content/en/docs/collector/trace-receiver.md
View File

@ -7,9 +7,11 @@ spelling: cSpell:ignore batchprocessor Rcvr uber atmxph comcast chicago
spelling: cSpell:ignore sanfrancisco ptrace pdata protogen pcommon stateid
spelling: cSpell:ignore ispnetwork serialnumber mcrsft gogl wndws slrs
spelling: cSpell:ignore backendsystem crand linux Intn semconv
spelling: cSpell:ignore
spelling: cSpell:ignore
---
<!-- markdownlint-disable heading-increment no-duplicate-heading -->
If you are reading this tutorial, you probably already have an idea of the
OpenTelemetry concepts behind distributed tracing, but if you don't you can
quickly read through it [here](/docs/concepts/signals/traces/).

1
content/en/docs/concepts/glossary.md
View File

@ -384,7 +384,6 @@ on web pages when requested. See [more][zpages].
[sampling]: /docs/specs/otel/trace/sdk#sampling
[signals]: /docs/concepts/signals/
[span]: /docs/specs/otel/trace/api#span
[spans]: /docs/specs/otel/trace/api#add-events
[spec-exporter-lib]: /docs/specs/otel/glossary/#exporter-library
[spec-instrumentation-lib]: /docs/specs/otel/glossary/#instrumentation-library
[spec-instrumented-lib]: /docs/specs/otel/glossary/#instrumented-library

2
content/en/docs/instrumentation/cpp/exporters.md
View File

@ -4,6 +4,8 @@ weight: 50
spelling: cSpell:ignore ostream jaegertracing millis chrono
---
<!-- markdownlint-disable no-duplicate-heading -->
In order to visualize and analyze your [traces](/docs/concepts/signals/traces/)
and metrics, you will need to export them to a backend.

4
content/en/docs/instrumentation/cpp/getting-started.md
View File

@ -20,8 +20,8 @@ application (a HTTP server & HTTP client). For more details read
You can build OpenTelemetry C++ on Windows, macOS or Linux. First you need to
install some dependencies:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
{{< tab "Linux (apt)" >}}
@ -43,8 +43,8 @@ brew install git cmake
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Building

2
content/en/docs/instrumentation/cpp/manual.md
View File

@ -6,6 +6,8 @@ description: Manual instrumentation for OpenTelemetry C++
spelling: cSpell:ignore nostd labelkv decltype nullptr
---
<!-- markdownlint-disable no-duplicate-heading -->
{{% docs/instrumentation/manual-intro %}}
## Setup

6
content/en/docs/instrumentation/erlang/exporters.md
View File

@ -28,6 +28,7 @@ Zipkin also run by [docker-compose](https://docs.docker.com/compose/).
To export to the running Collector the `opentelemetry_exporter` package must be
added to the project's dependencies:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -49,6 +50,7 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
It should then be added to the configuration of the Release before the SDK
Application to ensure the exporter's dependencies are started before the SDK
@ -57,6 +59,7 @@ attempts to initialize and use the exporter.
Example of Release configuration in `rebar.config` and for
[mix's Release task](https://hexdocs.pm/mix/Mix.Tasks.Release.html):
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -87,6 +90,7 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Finally, the runtime configuration of the `opentelemetry` and
`opentelemetry_exporter` Applications are set to export to the Collector. The
@ -95,6 +99,7 @@ the HTTP protocol with endpoint of `localhost` on port `4318`. If using `grpc`
for the `otlp_protocol` the endpoint should be changed to
`http://localhost:4317`.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -124,3 +129,4 @@ config :opentelemetry_exporter,
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->

16
content/en/docs/instrumentation/erlang/getting-started.md
View File

@ -5,6 +5,9 @@ spelling: cSpell:ignore rebar relx stdlib bogons defp rolldice
spelling: cSpell:ignore defmodule erts hipe Eshell postgres ecto elixirc KHTML
---
<!-- markdownlint-disable no-duplicate-heading -->
<!-- markdownlint-capture -->
Welcome to the OpenTelemetry for Erlang/Elixir getting started guide! This guide
will walk you through the basic steps in installing, configuring, and exporting
data from OpenTelemetry.
@ -251,6 +254,7 @@ get a random number in response, and 3 spans in your console.
```
</details>
<!-- markdownlint-disable heading-increment -->
##### `<<"/api/rolldice">>`
@ -299,6 +303,7 @@ more telemetry backends.
To get started with this guide, create a new project with `rebar3` or `mix`:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -312,11 +317,13 @@ mix new --sup otel_getting_started
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Then, in the project you just created, add both `opentelemetry_api` and
`opentelemetry` as dependencies. We add both because this is a project we will
run as a Release and export spans from.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -336,11 +343,13 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
In the case of Erlang, the API Application will also need to be added to
`src/otel_getting_started.app.src` and a `relx` section to `rebar.config`. In an
Elixir project, a `releases` section needs to be added to `mix.exs`:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -372,6 +381,7 @@ releases: [
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
The SDK `opentelemetry` should be added as early as possible in the Release boot
process to ensure it is available before any telemetry is produced. Here it is
@ -408,6 +418,7 @@ To configure OpenTelemetry to use a particular exporter, in this case
the `exporter` for the span processor `otel_batch_processor`, a type of span
processor that batches up multiple spans over a period of time:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -429,12 +440,14 @@ config :opentelemetry,
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Working with Spans
Now that the dependencies and configuration are set up, we can create a module
with a function `hello/0` that starts some spans:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -483,6 +496,7 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
In this example, we're using macros that use the process dictionary for context
propagation and for getting the tracer.
@ -507,6 +521,7 @@ To test out this project and see the spans created, you can run with
`rebar3 shell` or `iex -S mix`, each will pick up the corresponding
configuration for the release, resulting in the tracer and exporter to started.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -560,6 +575,7 @@ iex(2)>
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Next Steps

21
content/en/docs/instrumentation/erlang/manual.md
View File

@ -53,6 +53,7 @@ interactive shell, a `Tracer` with a blank name and version is used.
The created `Tracer`'s record can be looked up by the name of a module in the
OTP Application:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -66,6 +67,7 @@ opentelemetry:get_application_tracer(?MODULE)
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
This is how the Erlang and Elixir macros for starting and updating `Spans` get a
`Tracer` automatically without need for you to pass the variable in each call.
@ -75,6 +77,7 @@ This is how the Erlang and Elixir macros for starting and updating `Spans` get a
Now that you have [Tracer](/docs/concepts/signals/traces/#tracer)s initialized,
you can create [Spans](/docs/concepts/signals/traces/#spans).
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -99,12 +102,15 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
<!-- markdownlint-disable heading-increment -->
The above code sample shows how to create an active Span, which is the most
common kind of Span to create.
### Create Nested Spans
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -142,6 +148,7 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Spans in Separate Processes
@ -162,6 +169,7 @@ attaching the context and setting the new span as currently active in the
process. The whole context should be attached in order to not lose other
telemetry data like [baggage](/docs/specs/otel/baggage/api/).
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -198,6 +206,7 @@ _ = Task.await(task)
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Linking the New Span
@ -206,6 +215,7 @@ Span Links that causally link it to another Span. A
[Link](/docs/concepts/signals/traces/#span-links) needs a Span context to be
created.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -234,6 +244,7 @@ task = Task.async(fn ->
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Adding Attributes to a Span
@ -245,6 +256,7 @@ The following example shows the two ways of setting attributes on a span by both
setting an attribute in the start options and then again with `set_attributes`
in the body of the span operation:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -265,6 +277,7 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Semantic Attributes
@ -278,6 +291,7 @@ from the specification and provided in
For example, an instrumentation for an HTTP client or server would need to
include semantic attributes like the scheme of the URL:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -309,6 +323,7 @@ human-readable message on an
that represents a discrete event with no duration that can be tracked by a
single time stamp. You can think of it like a primitive log.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -330,9 +345,11 @@ Tracer.add_event("Did it!")
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Events can also have attributes of their own:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -346,6 +363,7 @@ Tracer.add_event("Process exited with reason", pid: pid, reason: Reason)
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Set Span Status
@ -357,6 +375,7 @@ could override the Error status with `StatusCode.OK`, but don’t set
The status can be set at any time before the span is finished:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -372,6 +391,7 @@ Tracer.set_status(:error, "this is not ok")
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Metrics
@ -392,4 +412,3 @@ You’ll also want to configure an appropriate exporter to
more telemetry backends.
[opentelemetry specification]: /docs/specs/otel/
[trace semantic conventions]: /docs/specs/otel/trace/semantic_conventions/

4
content/en/docs/instrumentation/erlang/propagation.md
View File

@ -26,6 +26,7 @@ propagators. By default the global propagators used are the W3C
These global propagators can be configured by the Application environment
variable `text_map_propagators`:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -46,6 +47,7 @@ text_map_propagators: [:baggage, :trace_context],
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Or through a comma separated list with the environment variable
`OTEL_PROPAGATORS`. Both forms of configuration accept the values
@ -55,6 +57,7 @@ and `b3multi`.
To manually inject or extract context the `otel_propagator_text_map` module can
be used:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -76,6 +79,7 @@ headers = :otel_propagator_text_map.inject([])
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
`otel_propagator_text_map:inject/1` and `otel_propagator_text_map:extract/1` use
globally registered propagators. To use a specific propagator

7
content/en/docs/instrumentation/erlang/resources.md
View File

@ -6,6 +6,9 @@ weight: 70
spelling: cSpell:ignore behaviour
---
<!-- markdownlint-disable no-duplicate-heading -->
<!-- markdownlint-capture -->
A [resource](/docs/specs/otel/overview/#resources) represents an entity
producing telemetry as attributes. For example, an OTP Release producing
telemetry that is running in a container on Kubernetes has an OTP Release name,
@ -26,6 +29,7 @@ detectors use the OS environment variable `OTEL_RESOURCE_ATTRIBUTES` and the
The detectors to use is a list of module names and can be configured in the
Application configuration:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -41,6 +45,7 @@ resource_detectors: [:otel_resource_env_var, :otel_resource_app_env]
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Or through the environment variable `OTEL_RESOURCE_DETECTORS`:
@ -67,6 +72,7 @@ OTEL_RESOURCE_ATTRIBUTES="deployment.environment=development"
Alternatively, use the `resource` Application environment under the
`opentelemetry` Application configuration of `sys.config` or `runtime.exs`:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -82,6 +88,7 @@ resource: %{deployment: %{environment: "development" }}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Resource attributes in the `resource` Application environment variable are
flattened and combined with `.`, so

14
content/en/docs/instrumentation/erlang/sampling.md
View File

@ -6,6 +6,9 @@ weight: 80
spelling: cSpell:ignore defmodule healthcheck behaviour
---
<!-- markdownlint-disable no-duplicate-heading -->
<!-- markdownlint-capture -->
[Sampling](/docs/concepts/sampling/) is a process that restricts the amount of
traces that are generated by a system. The Erlang SDK offers several
[head samplers](/docs/concepts/sampling#head-sampling).
@ -55,6 +58,7 @@ This tells the SDK to sample spans such that only 10% of Traces get created.
Example in the Application configuration with a root sampler for sampling 10% of
Traces and using the parent decision in the other cases:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -79,6 +83,8 @@ sampler: {:parent_based, %{root: {:trace_id_ratio_based, 0.10},
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
<!-- markdownlint-disable heading-increment -->
### AlwaysOn and AlwaysOff Sampler
@ -105,6 +111,7 @@ export OTEL_TRACES_SAMPLER="parentbased_always_off"
Here's an example in the Application configuration with a root sampler that
always samples and using the parent decision in the other cases:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -129,6 +136,7 @@ sampler: {:parent_based, %{root: :always_on,
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Custom Sampler
@ -136,6 +144,7 @@ Custom samplers can be created by implementing the
[`otel_sampler` behaviour](https://hexdocs.pm/opentelemetry/1.3.0/otel_sampler.html#callbacks).
This example sampler:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -189,11 +198,12 @@ defmodule AttributesSampler do
{:record_and_sample, [], []}
end
end
end
end
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Will sample Spans that do not have any attributes that match the attributes
passed as the sampler's configuration.
@ -201,6 +211,7 @@ passed as the sampler's configuration.
Example configuration to not sample any Span with an attribute specifying the
URL requested is `/healthcheck`:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -214,3 +225,4 @@ sampler: {AttributesSampler, %{"http.target": "/healthcheck"}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->

8
content/en/docs/instrumentation/erlang/testing.md
View File

@ -15,6 +15,7 @@ validation.
Only the `opentelemetry` and `opentelemetry_api` libraries are required for
testing in Elixir/Erlang:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -34,11 +35,13 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Set your `exporter` to `:none` and the span processor to
`:otel_simple_processor`. This ensure that your tests don't actually export data
to a destination, and that spans can be analyzed after they are processed.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -64,11 +67,13 @@ config :opentelemetry, :processors, [
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
A modified version of the `hello` function from the
[Getting Started](/docs/instrumentation/erlang/getting-started/) guide will
serve as our test case:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -105,9 +110,11 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Testing
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -199,3 +206,4 @@ end
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->

8
content/en/docs/instrumentation/java/getting-started.md
View File

@ -145,8 +145,8 @@ number of ways, the steps below use environment variables.
exporter][], using a notation suitable for your shell/terminal environment
&mdash; we illustrate a notation for bash-like shells:
```console
$ export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
```sh
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
OTEL_TRACES_EXPORTER=logging \
OTEL_METRICS_EXPORTER=logging \
OTEL_LOGS_EXPORTER=logging
@ -166,8 +166,8 @@ number of ways, the steps below use environment variables.
4. From _another_ terminal, send a request using `curl`:
```console
$ curl localhost:8080/rolldice
```sh
curl localhost:8080/rolldice
```
5. Stop the server process.

6
content/en/docs/instrumentation/java/manual.md
View File

@ -7,10 +7,12 @@ aliases:
- /docs/instrumentation/java/manual_instrumentation
weight: 30
description: Manual instrumentation for OpenTelemetry Java
spelling: cSpell:ignore logback multivalued autoconfigure classpath
spelling: cSpell:ignore logback multivalued autoconfigure classpath
spelling: cSpell:ignore customizer loggable
---
<!-- markdownlint-disable no-duplicate-heading -->
{{% docs/instrumentation/manual-intro %}}
## Setup
@ -1083,7 +1085,6 @@ io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extensio
https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpExchange.html
[instrumentation library]: /docs/specs/otel/glossary/#instrumentation-library
[instrumented library]: /docs/specs/otel/glossary/#instrumented-library
[library guidelines]: /docs/specs/otel/library-guidelines
[logs bridge API]: /docs/specs/otel/logs/bridge-api
[log data model]: /docs/specs/otel/logs/data-model
[log4j2 appender]:
@ -1103,6 +1104,5 @@ io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extensio
[parentbased]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/ParentBasedSampler.java
[releases]: https://github.com/open-telemetry/opentelemetry-java#releases
[semantic conventions]: /docs/specs/otel/trace/semantic_conventions
[traceidratiobased]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/TraceIdRatioBasedSampler.java

4
content/en/docs/instrumentation/js/exporters.md
View File

@ -28,6 +28,7 @@ update `instrumentation.ts|js` from the
[Getting Started](/docs/instrumentation/js/getting-started/nodejs/) like the
following:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -103,6 +104,7 @@ sdk.start();
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
To try out the `OTLPTraceExporter` quickly, you can run Jaeger in a docker
container:
@ -247,6 +249,7 @@ npm install --save @opentelemetry/exporter-zipkin
Update your OpenTelemetry configuration to use the exporter and to send data to
your Zipkin backend:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab Typescript >}}
@ -264,6 +267,7 @@ provider.addSpanProcessor(new BatchSpanProcessor(new ZipkinExporter()));
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
[content security policies]:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/

14
content/en/docs/instrumentation/js/getting-started/nodejs.md
View File

@ -39,6 +39,7 @@ npm init -y
Next, install Express dependencies.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
@ -56,12 +57,14 @@ npm install express
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Create and launch an HTTP Server
Create a file named `app.ts` (or `app.js` if not using TypeScript) and add the
following code to it:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -107,10 +110,12 @@ app.listen(PORT, () => {
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Run the application with the following command and open
<http://localhost:8080/rolldice> in your web browser to ensure it is working.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=console >}}
@ -126,13 +131,14 @@ Listening for requests on http://localhost:8080
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Instrumentation
The following shows how to install, initialize, and run an application
instrumented with OpenTelemetry.
### Dependencies
### More Dependencies
First, install the Node SDK and autoinstrumentations package.
@ -163,6 +169,7 @@ application code. One tool commonly used for this task is the
Create a file named `instrumentation.ts` (or `instrumentation.js` if not using
TypeScript) , which will contain your instrumentation setup code.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -208,12 +215,14 @@ sdk
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Run the instrumented app
Now you can run your application as you normally would, but you can use the
`--require` flag to load the instrumentation before the application code.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=console >}}
@ -229,6 +238,7 @@ Listening for requests on http://localhost:8080
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Open <http://localhost:8080/rolldice> in your web browser and reload the page a
few times. After a while you should see the spans printed in the console by the
@ -466,6 +476,7 @@ telemetry backends.
Did something go wrong? You can enable diagnostic logging to validate that
OpenTelemetry is initialized correctly:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -492,6 +503,7 @@ diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
[traces]: /docs/concepts/signals/traces/
[metrics]: /docs/concepts/signals/metrics/

6
content/en/docs/instrumentation/js/libraries.md
View File

@ -45,7 +45,7 @@ npm install @opentelemetry/auto-instrumentations-node
Then in your tracing initialization code, use `registerInstrumentations`:
<!-- textlint-disable -->
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -125,7 +125,7 @@ provider.register();
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
<!-- textlint-enable -->
### Using individual instrumentation packages
@ -145,6 +145,7 @@ npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrument
And then register each instrumentation library:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -230,6 +231,7 @@ provider.register();
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
## Configuring instrumentation libraries

24
content/en/docs/instrumentation/js/manual.md
View File

@ -38,6 +38,7 @@ npm install \
Next, create a separate `tracing.js|ts` file that has all the SDK initialization
code in it:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
@ -107,10 +108,12 @@ provider.register();
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Next, ensure that `tracing.js|ts` is required in your node invocation. This is
also required if you're registering instrumentation libraries. For example:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
@ -124,6 +127,7 @@ node --require ./tracing.js <app-file.js>
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
#### Browser
@ -141,6 +145,7 @@ npm install \
Create a `tracing.js|ts` file that initialized the Web SDK, creates a
`TracerProvider`, and exports a `Tracer`.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -206,6 +211,7 @@ provider.register();
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
You'll need to bundle this file with your web application to be able to use
tracing throughout the rest of your web application.
@ -233,6 +239,7 @@ In most cases, stick with `BatchSpanProcessor` over `SimpleSpanProcessor`.
Anywhere in your application where you write manual tracing code should call
`getTracer` to acquire a tracer. For example:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -257,6 +264,7 @@ const tracer = opentelemetry.trace.getTracer(
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
It's generally recommended to call `getTracer` in your app when you need it
rather than exporting the `tracer` instance to the rest of your app. This helps
@ -417,6 +425,7 @@ npm install --save @opentelemetry/semantic-conventions
Add the following to the top of your application file:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -427,6 +436,7 @@ const { SemanticAttributes } = require('@opentelemetry/semantic-conventions');
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Finally, you can update your file to include semantic attributes:
@ -500,6 +510,7 @@ typically used to specify that a span has not completed successfully -
The status can be set at any time before the span is finished:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -540,6 +551,7 @@ tracer.startActiveSpan('app.doWork', span => {
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
By default, the status for all spans is `Unset` rather than `Ok`. It is
typically the job of another component in your telemetry pipeline to interpret
@ -551,6 +563,7 @@ explicitly tracking an error.
It can be a good idea to record exceptions when they happen. It's recommended to
do this in conjunction with setting [span status](#span-status).
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -579,6 +592,7 @@ try {
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Using `sdk-trace-base` and manually propagating span context
@ -591,6 +605,7 @@ nested spans.
Initializing tracing is similar to how you'd do it with Node.js or the Web SDK.
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -633,6 +648,7 @@ const tracer = opentelemetry.trace.getTracer(
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Like the other examples in this document, this exports a tracer you can use
throughout the app.
@ -721,6 +737,7 @@ npm install \
Next, create a separate `instrumentation.js|ts` file that has all the SDK
initialization code in it:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -794,9 +811,11 @@ opentelemetry.metrics.setGlobalMeterProvider(myServiceMeterProvider)
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
You'll need to `--require` this file when you run your app, such as:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane lang=shell >}}
@ -810,6 +829,7 @@ node --require ./instrumentation.js <app-file.js>
{{< /tabpane >}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
Now that a `MeterProvider` is configured, you can acquire a `Meter`.
@ -818,6 +838,7 @@ Now that a `MeterProvider` is configured, you can acquire a `Meter`.
Anywhere in your application where you have manually instrumented code you can
call `getMeter` to acquire a meter. For example:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -841,6 +862,7 @@ const myMeter = opentelemetry.metrics.getMeter(
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
It’s generally recommended to call `getMeter` in your app when you need it
rather than exporting the meter instance to the rest of your app. This helps
@ -912,6 +934,7 @@ Histograms are used to measure a distribution of values over time.
For example, here's how you might report a distribution of response times for an
API route with Express:
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
{{< tabpane langEqualsHeader=true >}}
{{< tab TypeScript >}}
@ -953,6 +976,7 @@ app.get('/', (_req, _res) => {
{{< /tab >}}
{{< /tabpane>}}
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->
### Using Observable (Async) Counters

2
content/en/docs/instrumentation/php/manual.md
View File

@ -6,6 +6,8 @@ description: Manual instrumentation for OpenTelemetry PHP
spelling: cSpell:ignore myapp autoload guzzlehttp
---
<!-- markdownlint-disable no-duplicate-heading -->
{{% docs/instrumentation/manual-intro %}}
## Installation

50
content/en/docs/instrumentation/python/automatic/example.md
View File

@ -85,10 +85,10 @@ def server_request():
Execute the following example in a separate virtual environment. Run the
following commands to prepare for auto-instrumentation:
```console
$ mkdir auto_instrumentation
$ virtualenv auto_instrumentation
$ source auto_instrumentation/bin/activate
```sh
mkdir auto_instrumentation
virtualenv auto_instrumentation
source auto_instrumentation/bin/activate
```
## Install
@ -98,11 +98,11 @@ Run the following commands to install the appropriate packages. The
for custom instrumentation of your own code and `opentelemetry-instrumentation`
which provides several commands that help automatically instrument a program.
```console
$ pip install opentelemetry-distro
$ pip install opentelemetry-instrumentation-flask
$ pip install flask
$ pip install requests
```sh
pip install opentelemetry-distro
pip install opentelemetry-instrumentation-flask
pip install flask
pip install requests
```
The examples that follow send instrumentation results to the console. Learn more
@ -129,14 +129,14 @@ well as the process of executing an automatically instrumented server.
Execute the server in two separate consoles, one to run each of the scripts that
make up this example:
```console
$ source auto_instrumentation/bin/activate
$ python server_manual.py
```sh
source auto_instrumentation/bin/activate
python server_manual.py
```
```console
$ source auto_instrumentation/bin/activate
$ python client.py testing
```sh
source auto_instrumentation/bin/activate
python client.py testing
```
The console running `server_manual.py` will display the spans generated by
@ -184,15 +184,15 @@ example:
Stop the execution of `server_manual.py` by pressing <kbd>Control+C</kbd> and
run the following command instead:
```console
$ opentelemetry-instrument --traces_exporter console --metrics_exporter none python server_automatic.py
```sh
opentelemetry-instrument --traces_exporter console --metrics_exporter none python server_automatic.py
```
In the console where you previously executed `client.py`, run the following
command again:
```console
$ python client.py testing
```sh
python client.py testing
```
The console running `server_automatic.py` will display the spans generated by
@ -315,10 +315,10 @@ of HTTP header names via the environment variables
`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST` and
`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`, e.g.:
```console
$ export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="Accept-Encoding,User-Agent,Referer"
$ export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="Last-Modified,Content-Type"
$ opentelemetry-instrument --traces_exporter console --metrics_exporter none python app.py
```sh
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="Accept-Encoding,User-Agent,Referer"
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="Last-Modified,Content-Type"
opentelemetry-instrument --traces_exporter console --metrics_exporter none python app.py
```
These configuration options are supported by the following HTTP
@ -351,10 +351,6 @@ If those headers are available, they will be included in your span:
/docs/specs/otel/trace/semantic_conventions/http/#http-request-and-response-headers
[api reference]:
https://opentelemetry-python.readthedocs.io/en/latest/index.html
[distro]:
https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-distro
[env]:
https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html
[instrumentation]:
https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation
[monkey-patching]:

8
content/en/docs/instrumentation/python/distro.md
View File

@ -25,8 +25,8 @@ any other code is executed.
In order to automatically export data from OpenTelemetry to the OpenTelemetry
collector, installing the package will set up all the required entry points.
```console
$ pip install opentelemetry-distro[otlp] opentelemetry-instrumentation
```sh
pip install opentelemetry-distro[otlp] opentelemetry-instrumentation
```
Start the Collector locally to see data being exported. Write the following
@ -74,8 +74,8 @@ with trace.get_tracer("my.tracer").start_as_current_span("foo"):
Lastly, run the `no_configuration.py` with the auto-instrumentation:
```console
$ opentelemetry-instrument python no_configuration.py
```sh
opentelemetry-instrument python no_configuration.py
```
The resulting span will appear in the output from the collector and look similar

46
content/en/docs/instrumentation/python/exporters.md
View File

@ -4,6 +4,8 @@ weight: 50
spelling: cSpell:ignore LOWMEMORY proto
---
<!-- markdownlint-disable no-duplicate-heading -->
In order to visualize and analyze your telemetry you will need to use an
exporter.
@ -49,8 +51,8 @@ There are temporality presets for each instrumentation kind. These presets can
be set with the environment variable
`OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE`, for example:
```console
$ export OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE="DELTA"
```sh
export OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE="DELTA"
```
The default value for `OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE` is
@ -115,8 +117,8 @@ configure an OTLP exporter that sends to your endpoint.
First, install an OTLP exporter:
```console
$ pip install opentelemetry-exporter-otlp-proto-grpc
```sh
pip install opentelemetry-exporter-otlp-proto-grpc
```
### Trace
@ -167,8 +169,8 @@ metrics.set_meter_provider(provider)
If you'd prefer to use [OTLP/HTTP](/docs/specs/otlp/#otlphttp) with the
binary-encoded protobuf format, you can install the package:
```console
$ pip install opentelemetry-exporter-otlp-proto-http
```sh
pip install opentelemetry-exporter-otlp-proto-http
```
Next, replace the import declarations with the following:
@ -191,8 +193,8 @@ If you are using [Jaeger](https://www.jaegertracing.io/) to visualize trace
data, you'll need to set it up first. This is how to run it in a docker
container:
```console
$ docker run -d --name jaeger \
```sh
docker run -d --name jaeger \
-e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
-p 5775:5775/udp \
-p 6831:6831/udp \
@ -207,8 +209,8 @@ $ docker run -d --name jaeger \
Next, install the Jaeger exporter package:
```console
$ pip install opentelemetry-exporter-jaeger
```sh
pip install opentelemetry-exporter-jaeger
```
This will install packages for both:
@ -257,14 +259,14 @@ from opentelemetry.exporter.jaeger.proto.grpc import JaegerExporter
If you are using [Zipkin](https://zipkin.io/) to visualize trace data, you'll
need to set it up first. This is how to run it in a docker container:
```console
$ docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin
```sh
docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin
```
Next, install the Zipkin exporter package:
```console
$ pip install opentelemetry-exporter-zipkin-proto-http
```sh
pip install opentelemetry-exporter-zipkin-proto-http
```
Then you can configure the exporter when initializing tracing:
@ -294,8 +296,8 @@ trace.set_tracer_provider(provider)
If you'd prefer to use Thrift as the protocol, you can install the package:
```console
$ pip install opentelemetry-exporter-zipkin-json
```sh
pip install opentelemetry-exporter-zipkin-json
```
And replace the `ZipkinExporter` import declaration with the following:
@ -311,8 +313,8 @@ you'll need to set it up first.
First create a config file:
```console
$ cat > prometheus.yml <<EOF
```bash
cat > prometheus.yml <<EOF
scrape_configs:
- job_name: 'otel-python-demo'
scrape_interval: 5s
@ -323,8 +325,8 @@ EOF
Then start the Prometheus server in Docker:
```console
$ docker run -d --rm \
```sh
docker run -d --rm \
--network=host \
-v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
prom/prometheus
@ -332,8 +334,8 @@ $ docker run -d --rm \
Next, install the Prometheus exporter package:
```console
$ pip install opentelemetry-exporter-prometheus
```sh
pip install opentelemetry-exporter-prometheus
```
Then you can configure the exporter when initializing metrics:

2
content/en/docs/instrumentation/python/manual.md
View File

@ -6,6 +6,8 @@ description: Manual instrumentation for OpenTelemetry Python
spelling: cSpell:ignore ottrace textmap millis
---
<!-- markdownlint-disable no-duplicate-heading -->
{{% docs/instrumentation/manual-intro %}}
## Setup

3
content/en/docs/instrumentation/ruby/manual.md
View File

@ -368,7 +368,4 @@ more telemetry backends.
https://github.com/open-telemetry/opentelemetry-ruby/tree/main/propagator
[auto-instrumentation]:
https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation
[semconv-gem]:
https://github.com/open-telemetry/opentelemetry-ruby/tree/main/semantic_conventions
[semconv-spec]: /docs/specs/otel/trace/semantic_conventions/
[opentelemetry specification]: /docs/specs/otel/

2
content/en/docs/instrumentation/swift/libraries.md
View File

@ -6,6 +6,8 @@ weight: 40
spelling: cSpell:ignore iphone darwin NSURL inout wifi
---
<!-- markdownlint-disable no-duplicate-heading -->
OpenTelemetry-Swift provides several instrumentation libraries that generate
instrumentation for you when they're installed and initialized.

4
content/en/docs/k8s-operator/_index.md
View File

@ -26,13 +26,13 @@ To install the operator in an existing cluster, make sure you have cert-manager
installed and run:
```bash
$ kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
```
Once the `opentelemetry-operator` deployment is ready, create an OpenTelemetry
Collector (otelcol) instance, like:
```bash
```console
$ kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector

2
content/en/ecosystem/registry/_index.md
View File

@ -16,6 +16,8 @@ weight: 20
{{% blocks/lead color="white" %}}
<!-- markdownlint-disable single-h1 -->
# {{% param title %}}
{{% param description %}}

95
gulp-src/lint-md.js Normal file
View File

@ -0,0 +1,95 @@
const gulp = require('gulp');
const through2 = require('through2');
const markdownlint = require('markdownlint');
const { taskArgs } = require('./_util');
const fs = require('fs');
const defaultGlob = '**/*.md';
const markdownFiles = [
'!.github/**',
'!content-modules/**',
'!layouts/**',
'!node_modules/**',
'!themes/**',
'!tmp/**',
];
let fileCounter = 0,
issueCount = 0;
function markdownLintFile(file, encoding, callback) {
// const config = require('../.markdownlint.json');
const config = JSON.parse(fs.readFileSync('./.markdownlint.json'));
const placeholder = 'lint-md';
const options = {
// We would normally just pass in the file like this:
//
// files: [file.path],
//
// But since the checker doesn't understand Hugo {{...}} syntax, we replace
// such expressions with a placeholder and pass in the simplified file
// content.
strings: {
[file.path]: file.contents
.toString()
.replace(/\{\{[^\}]+\}\}/g, placeholder),
},
config: config,
};
markdownlint(options, function (err, result) {
if (err) {
console.error('ERROR occurred while running markdownlint: ', err);
return callback(err);
}
const _resultString = (result || '').toString();
// Result is a string with lines of the form:
//
// <file-path>:\s*<line-number>: <ID-and-message>
//
// Strip out any whitespace between the filepath and line number
// so that tools can jump directly to the line.
const resultString = _resultString
.split('\n')
.map((line) => line.replace(/^([^:]+):\s*(\d+):(.*)/, '$1:$2:$3'))
.join('\n');
if (resultString) {
console.log(resultString);
issueCount++;
}
fileCounter++;
callback(null, file);
});
}
function lintMarkdown() {
const argv = taskArgs().options({
glob: {
alias: 'g',
type: 'string',
description: 'Glob of files to run through markdownlint.',
default: defaultGlob,
},
}).argv;
if (argv.info) {
// Info about options was already displayed by yargs.help().
return Promise.resolve();
}
return gulp
.src([argv.glob, ...markdownFiles])
.pipe(through2.obj(markdownLintFile))
.on('end', () => {
console.log(
`Processed ${fileCounter} file${
fileCounter == 1 ? '' : 's'
}, ${issueCount} had issues.`,
);
});
}
lintMarkdown.description = `Check markdownlint rules. For details, use --info.`;
gulp.task('lint-md', lintMarkdown);

6
package.json
View File

@ -39,6 +39,7 @@
"check:format": "npm run _check:format || (echo '[help] Run: npm run format'; exit 1)",
"check:links": "npm run _check:links",
"check:links:internal": "npm run _check:links:internal",
"check:markdown": "npx gulp lint-md",
"check:spelling": "npm run _check:spelling",
"check:text": "npm run _check:text",
"clean": "make clean",
@ -79,6 +80,7 @@
"cspell": "^6.31.1",
"gulp": "^4.0.2",
"hugo-extended": "0.115.2",
"markdownlint": "^0.29.0",
"netlify-cli": "^15.8.1",
"npm-run-all": "^4.1.5",
"postcss-cli": "^10.1.0",
@ -87,7 +89,9 @@
"textlint": "^13.1.4",
"textlint-filter-rule-allowlist": "^4.0.0",
"textlint-filter-rule-comments": "^1.2.2",
"textlint-rule-terminology": "^3.0.4"
"textlint-rule-terminology": "^3.0.4",
"through2": "^4.0.2",
"yargs": "^17.7.2"
},
"dependencies": {
"@opentelemetry/api": "^1.3.0",