inits Deployment contrib #2312

mhausenblas · 2023-02-09T13:39:46Z

Addresses #1696

Preview: https://deploy-preview-2312--opentelemetry.netlify.app/docs/collector/deployment/

chalin · 2023-02-10T18:49:03Z

content/en/docs/collector/deployment.md

+
+The collector would then be configured like so:
+
+{{< ot-tabs Traces Metrics Logs >}} {{< ot-tab lang="yaml">}}


FYI, we're trying to phase out the use of the ot-tabs shortcode (for details see #1820). Since you seem to be on a roll in terms of creating new content, would you be willing to switch to using the Docsy tabpane shortcode instead?

Here's an example:

opentelemetry.io/content/en/docs/instrumentation/js/instrumentation.md

Lines 39 to 105 in e3edb62

{{< tabpane langEqualsHeader=true >}}

{{< tab TypeScript >}}

/*tracing.ts*/

import { BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";

import { Resource } from "@opentelemetry/resources";

import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

import { registerInstrumentations } from "@opentelemetry/instrumentation";

// Optionally register instrumentation libraries

registerInstrumentations({

instrumentations: [],

});

const resource =

Resource.default().merge(

new Resource({

[SemanticResourceAttributes.SERVICE_NAME]: "service-name-here",

[SemanticResourceAttributes.SERVICE_VERSION]: "0.1.0",

})

);

const provider = new NodeTracerProvider({

resource: resource,

});

const exporter = new ConsoleSpanExporter();

const processor = new BatchSpanProcessor(exporter);

provider.addSpanProcessor(processor);

provider.register();

{{< /tab >}}

{{< tab JavaScript >}}

/*tracing.js*/

const opentelemetry = require("@opentelemetry/api");

const { Resource } = require("@opentelemetry/resources");

const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");

const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");

const { registerInstrumentations } = require("@opentelemetry/instrumentation");

const { ConsoleSpanExporter, BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");

// Optionally register instrumentation libraries

registerInstrumentations({

instrumentations: [],

});

const resource =

Resource.default().merge(

new Resource({

[SemanticResourceAttributes.SERVICE_NAME]: "service-name-here",

[SemanticResourceAttributes.SERVICE_VERSION]: "0.1.0",

})

);

const provider = new NodeTracerProvider({

resource: resource,

});

const exporter = new ConsoleSpanExporter();

const processor = new BatchSpanProcessor(exporter);

provider.addSpanProcessor(processor);

provider.register();

{{< /tab >}}

{{< /tabpane>}}

OK, I got it to work after some wrangling, here's what I'm using:

 {{< tabpane persistLang=false >}} {{< tab header="Traces" lang="yaml" >}} ...

Note that the lang doesn't inherit as per docs and without the persistLang=false the rendering is screwed.

cartermp

Left a review pass with some questions and suggestions. Thank you, this is really great content overall!

cartermp · 2023-02-12T19:12:22Z

content/en/docs/collector/deployment/_index.md

+The OpenTelemetry collector consists of a single binary which you can use in
+different ways, for different use cases. This section describes deployment
+patterns, their use cases along with pros and cons and best practices for
+collector configurations for cross-environment and multi-backend deployments.


Suggested change

The OpenTelemetry collector consists of a single binary which you can use in

different ways, for different use cases. This section describes deployment

patterns, their use cases along with pros and cons and best practices for

collector configurations for cross-environment and multi-backend deployments.

The OpenTelemetry collector consists of a single binary that you can use in

different ways, for different use cases. This section describes deployment

patterns, their use cases along with pros and cons, and best practices for

collector configurations for cross-environment and multi-backend deployments.

cartermp · 2023-02-12T19:13:19Z

content/en/docs/collector/deployment/best-practices.md

+
+## Normalizing
+
+Normalize the metadata from different instrumentations


Suggested change

Normalize the metadata from different instrumentations

Normalize instrumentation from different sources.

cartermp · 2023-02-12T19:13:42Z

content/en/docs/collector/deployment/best-practices.md

+
+## Multitenancy
+
+You want to isolate different tenants (customers, teams, etc.)


Suggested change

You want to isolate different tenants (customers, teams, etc.)

Isolate different tenants (customers, teams, etc.)

cartermp · 2023-02-12T19:13:55Z

content/en/docs/collector/deployment/best-practices.md

+You want to aggregate signals from multiple environments (on-prem, Kubernetes,
+etc.)


Suggested change

You want to aggregate signals from multiple environments (on-prem, Kubernetes,

etc.)

Aggregate signals from multiple environments (on-prem, Kubernetes,

etc.)

cartermp · 2023-02-12T19:14:15Z

content/en/docs/collector/deployment/best-practices.md

+Have one collector instance per signal type, for example, one dedicated to
+Prometheus metrics, one dedicated to Jaeger traces.


Suggested change

Have one collector instance per signal type, for example, one dedicated to

Prometheus metrics, one dedicated to Jaeger traces.

One collector instance per signal type. For example, one dedicated to

Prometheus metrics and one dedicated to Jaeger traces.

Is this referring to a export or ingest or both?

cartermp · 2023-02-13T00:36:20Z

content/en/docs/collector/deployment/centralized.md

+
+Cons:
+
+- Effort


Compared to what?

cartermp · 2023-02-13T00:37:11Z

content/en/docs/collector/deployment/decentralized.md

+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.
+
+## Tradeoffs


This and the other tradeoffs sections aren't quite clear to me. Is this comparing centralized vs. decentralized collector deployment patterns? If so, I'd call it out explicitly in both docs sections.

cartermp · 2023-02-13T01:41:28Z

content/en/docs/collector/deployment/decentralized.md

+The decentralized collector deployment pattern consists of
+applications—[instrumented][instrumentation] with an OpenTelemetry SDK using
+[OpenTelemetry protocol (OTLP)][otlp]—or other collectors (using the OTLP
+exporter) that send telemetry signals to one or more [collectors][collector].
+Each client-side SDK or downstream collector is configured with a collector
+location:


I found this paragraph difficult to parse. I also found it hard to understand how this pattern differs from the other since you mention several SDKs or collectors sending data to other collectors. Is the difference just that there isn't a load balancer?

cartermp · 2023-02-13T01:49:29Z

content/en/docs/collector/deployment/decentralized.md

+like so:
+
+<!-- prettier-ignore-start -->
+{{< ot-tabs Traces Metrics Logs >}}


Hmmm. Why is there an example for traces when the example scenario described above is just emitting metrics? I think the example scenario above should be changed to also include traces.

I'm also curious why this example uses the "one collector per signal type" pattern here. Is that something we should recommend for people, or is it just happenstance that it's the example chosen here?

cartermp · 2023-02-13T01:53:11Z

content/en/docs/collector/deployment/no-collector.md

+- Simple to use (especially in a dev/test environment)
+- No additional moving parts to operate (in production environments)
+
+Cons:


Might be good to link to this section and/or amend it to have more examples.

smithclay · 2023-02-13T22:55:49Z

content/en/docs/collector/deployment/_index.md

+patterns, their use cases along with pros and cons and best practices for
+collector configurations for cross-environment and multi-backend deployments.
+
+## Other information


One question that has come up fairly frequently regarding collector deployments is "when/why should I use the Collector Operator?"

Would be helpful for end-users if the intro mentioned how the operator (optionally) fits into k8s-based deployments.

@mhausenblas, wdyt? I am always a fan of having inter-linked pages to point people to other resources (not the repo, but the docs for k8s operator at /docs/k8s-operator/), but I don't see yet how to incorporate that to this page.

mhausenblas · 2023-03-06T09:40:11Z

FYI: aiming to complete this entry in W10 and also I will add the side car pattern to Decentralized section.

svrnm · 2023-02-12T12:12:16Z

content/en/docs/collector/deployment/best-practices.md

+weight: 4
+---
+
+Now that you are equipped with the essential deployment patterns for the


link back to the "essential deployment patterns" so if people land here first they figure out where to go for this.

svrnm · 2023-03-06T11:21:22Z

content/en/docs/collector/deployment/no-collector.md

+Cons:
+
+- Requires code changes if collection, processing, or ingestion changes
+- Strong coupling between the application code and the backend


I think there are more disadvantages we should list:

SDK needs to take care of authentication, connection management (reconnections, etc.), encryption, etc.

Long round time times to the backend increase overhead at the application level

...

svrnm · 2023-03-06T11:22:55Z

content/en/docs/collector/deployment/decentralized.md

+A concrete example of the decentralized collector deployment pattern could look
+as follows: you manually instrument, say, a [Java application to export
+metrics][instrument-java-metrics] using the OpenTelemetry Java SDK. In the
+context of the app, you would set the `OTEL_METRICS_EXPORTER` to `otlp` (which
+is the default value) and configure the [OTLP exporter][otlp-exporter] with the
+address of your collector, for example (in Bash or `zsh` shell):


Suggested change

A concrete example of the decentralized collector deployment pattern could look

as follows: you manually instrument, say, a [Java application to export

metrics][instrument-java-metrics] using the OpenTelemetry Java SDK. In the

context of the app, you would set the `OTEL_METRICS_EXPORTER` to `otlp` (which

is the default value) and configure the [OTLP exporter][otlp-exporter] with the

address of your collector, for example (in Bash or `zsh` shell):

A concrete example of the decentralized collector deployment pattern could look

as follows: you manually instrument a [Java application to export

metrics][instrument-java-metrics] using the OpenTelemetry Java SDK. In the

context of the app, you would set the `OTEL_METRICS_EXPORTER` to `otlp` (which

is the default value) and configure the [OTLP exporter][otlp-exporter] with the

address of your collector, for example (in Bash or `zsh` shell):

mviitane · 2023-03-08T08:27:07Z

content/en/docs/collector/deployment/centralized.md

+weight: 3
+---
+
+The centralized collector deployment pattern consists of applications (or other


I’d have two main scenarios with separate pictures. First one with multiple applications sending to one Collector (basic setup). The second one could be this load-balanced scenario, but with multiple applications to visualize the centralized pattern.

mviitane · 2023-03-08T08:30:36Z

content/en/docs/collector/deployment/decentralized.md

+Each client-side SDK or downstream collector is configured with a collector
+location:
+
+![Decentralized collector deployment concept](../../img/decentralized-sdk.svg)


For me, this picture doesn’t really capture the decentralized pattern and 1:1 relationship between the application and Collector. You could add 3 apps and 3 Collectors (1-1 connected) to make this visible.

mviitane · 2023-03-08T08:33:26Z

content/en/docs/collector/deployment/decentralized.md

+
+- Simple to get started
+- Clear 1:1 mapping between application and collector
+


You could mention the benefit to offload applications for batching, retry, encryption, compression, and more.

mviitane · 2023-03-08T08:37:29Z

content/en/docs/collector/deployment/centralized.md

+- Centralized policy management
+
+Cons:
+


These could be added as cons:

Single point of failure

Can lead to high load levels, if not dimensioned properly

mx-psi · 2023-03-09T10:37:54Z

content/en/docs/collector/deployment/_index.md

+## Other information
+
+- GitHub repo [OpenTelemetry Collector Deployment Patterns][gh-patterns]
+- YouTube video [OpenTelemetry Collector Deployment Patterns][y-patterns]


I would make it clear that this is a talk

Suggested change

- YouTube video [OpenTelemetry Collector Deployment Patterns][y-patterns]

- KubeCon NA 2021 Talk [OpenTelemetry Collector Deployment Patterns][y-patterns]

Good suggested change, but drop the quotes.

edited, thanks for the feedback :)

mx-psi · 2023-03-09T10:39:00Z

content/en/docs/collector/deployment/_index.md

+
+## Other information
+
+- GitHub repo [OpenTelemetry Collector Deployment Patterns][gh-patterns]


Suggested change

- GitHub repo [OpenTelemetry Collector Deployment Patterns][gh-patterns]

- [Repository with full configuration examples for different deployment patterns][gh-patterns]

mx-psi · 2023-03-09T10:41:23Z

content/en/docs/collector/deployment/_index.md

+The OpenTelemetry collector consists of a single binary which you can use in
+different ways, for different use cases. This section describes deployment
+patterns, their use cases along with pros and cons and best practices for
+collector configurations for cross-environment and multi-backend deployments.


nit: make the first sentence structure simpler

Suggested change

The OpenTelemetry collector consists of a single binary which you can use in

different ways, for different use cases. This section describes deployment

patterns, their use cases along with pros and cons and best practices for

collector configurations for cross-environment and multi-backend deployments.

You can deploy the OpenTelemetry collector in different ways depending on your

use case. This section describes deployment

patterns, their use cases along with pros and cons and best practices for

collector configurations for cross-environment and multi-backend deployments.

mx-psi · 2023-03-09T10:43:09Z

content/en/docs/collector/deployment/best-practices.md

+  jaeger:
+    endpoint: "https://jaeger.example.com:14250"
+    insecure: true


We have deprecated the Jaeger exporter, so I would recommend using the OTLP exporter instead

mx-psi · 2023-03-09T10:44:27Z

content/en/docs/collector/deployment/best-practices.md

+receivers:
+  otlp:
+    protocols:
+      grpc:


Using this configuration will produce a warning about DoS attacks (see here). We should set the endpoint explicitly

mx-psi · 2023-03-09T10:46:53Z

content/en/docs/collector/deployment/centralized.md

+receivers:
+  otlp:
+    protocols:
+      grpc:


mx-psi · 2023-03-09T10:47:02Z

content/en/docs/collector/deployment/centralized.md

+  otlp:
+    protocols:
+      grpc:
+


mx-psi · 2023-03-09T10:47:37Z

content/en/docs/collector/deployment/decentralized.md

+receivers:
+  otlp: # the OTLP receiver the app is sending traces to
+    protocols:
+      grpc:


mx-psi · 2023-03-09T10:47:51Z

content/en/docs/collector/deployment/decentralized.md

+  jaeger: # the Jaeger exporter, to ingest traces to backend
+    endpoint: "https://jaeger.example.com:14250"
+    insecure: true


ditto (use OTLP exporter)

mx-psi · 2023-03-09T10:48:01Z

content/en/docs/collector/deployment/decentralized.md

+receivers:
+  otlp: # the OTLP receiver the app is sending logs to
+    protocols:
+      grpc:


dmitryax · 2023-03-09T18:56:16Z

Are we introducing new deployment concepts or replacing Agent/Gateway with Decentralized/Centralized as 1:1? It doesn't seem to be 1:1 based on the docs:

Agent is supposed to represent an installation on one host so that instrumentation libraries can point to local endpoints like http://localhost:4318. The decentralized doc says collector.example.com:4318 instead. Also, the decentralized section mentions "Clear 1:1 mapping between application and collector" in "Pros" section, which is right for the agent term as well, but it confuses me when I read the first paragraph that seems to contradict:

The decentralized collector deployment pattern consists of applications—instrumented with an OpenTelemetry SDK using OpenTelemetry protocol (OTLP)—or other collectors (using the OTLP exporter) that send telemetry signals to one or more collectors.

Several Collector pull-based receivers are intended to run in the agent (decentralized?) mode, for example, hostmetrics receiver. If we are extending the documentation, I believe it's worth mentioning.

In general, I don't fully agree that decentralized/centralized terms are easier to understand than agent/gateway. I'd like to bring this to discussion for the Collector SIG meeting.

cc @open-telemetry/collector-approvers

mhausenblas · 2023-03-13T15:09:40Z

Argh, didn't mean to close the PR, just catching up with main :(

svrnm · 2023-03-13T15:11:51Z

Argh, didn't mean to close the PR, just catching up with main :(

you should be able to reopen it with a force push

mhausenblas added 4 commits February 9, 2023 13:38

inits Deployment contrib

b3719fe

inits figures

18f1272

expands on dede pattern content

6fa5b65

fixes formatting

c71aa2e

chalin reviewed Feb 10, 2023

View reviewed changes

mhausenblas added 4 commits February 11, 2023 07:21

expands on centralized pattern

56219a8

expands on centralized pattern

cd50ad1

adds no collector and expands on best practices

26a1c05

splits up content

d860861

cartermp reviewed Feb 13, 2023

View reviewed changes

smithclay reviewed Feb 13, 2023

View reviewed changes

mhausenblas mentioned this pull request Feb 28, 2023

collector architecture open-telemetry/opentelemetry-collector-contrib#18919

Closed

mhausenblas self-assigned this Mar 6, 2023

mhausenblas marked this pull request as ready for review March 6, 2023 09:37

mhausenblas requested review from a team and codeboten and removed request for a team March 6, 2023 09:37

svrnm reviewed Mar 6, 2023

View reviewed changes

mviitane reviewed Mar 8, 2023

View reviewed changes

mx-psi reviewed Mar 9, 2023

View reviewed changes

mhausenblas added 2 commits March 13, 2023 14:27

updates deployment patterns

5279604

updates deployment patterns

c296a8d

updates deployment patterns

1f57d7a

mhausenblas closed this Mar 13, 2023

mhausenblas deleted the col-deploy branch March 13, 2023 15:00

mhausenblas mentioned this pull request Mar 13, 2023

inits Deployment contrib #2498

Merged


		The collector would then be configured like so:

		{{< ot-tabs Traces Metrics Logs >}} {{< ot-tab lang="yaml">}}

	{{< tabpane langEqualsHeader=true >}}

	{{< tab TypeScript >}}
	/tracing.ts/
	import { BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
	import { Resource } from "@opentelemetry/resources";
	import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
	import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
	import { registerInstrumentations } from "@opentelemetry/instrumentation";


	// Optionally register instrumentation libraries
	registerInstrumentations({
	instrumentations: [],
	});

	const resource =
	Resource.default().merge(
	new Resource({
	[SemanticResourceAttributes.SERVICE_NAME]: "service-name-here",
	[SemanticResourceAttributes.SERVICE_VERSION]: "0.1.0",
	})
	);

	const provider = new NodeTracerProvider({
	resource: resource,
	});
	const exporter = new ConsoleSpanExporter();
	const processor = new BatchSpanProcessor(exporter);
	provider.addSpanProcessor(processor);

	provider.register();
	{{< /tab >}}

	{{< tab JavaScript >}}
	/tracing.js/
	const opentelemetry = require("@opentelemetry/api");
	const { Resource } = require("@opentelemetry/resources");
	const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");
	const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
	const { registerInstrumentations } = require("@opentelemetry/instrumentation");
	const { ConsoleSpanExporter, BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");

	// Optionally register instrumentation libraries
	registerInstrumentations({
	instrumentations: [],
	});

	const resource =
	Resource.default().merge(
	new Resource({
	[SemanticResourceAttributes.SERVICE_NAME]: "service-name-here",
	[SemanticResourceAttributes.SERVICE_VERSION]: "0.1.0",
	})
	);

	const provider = new NodeTracerProvider({
	resource: resource,
	});
	const exporter = new ConsoleSpanExporter();
	const processor = new BatchSpanProcessor(exporter);
	provider.addSpanProcessor(processor);

	provider.register();
	{{< /tab >}}

	{{< /tabpane>}}


		## Normalizing

		Normalize the metadata from different instrumentations

	Normalize the metadata from different instrumentations
	Normalize instrumentation from different sources.


		## Multitenancy

		You want to isolate different tenants (customers, teams, etc.)

	You want to isolate different tenants (customers, teams, etc.)
	Isolate different tenants (customers, teams, etc.)

		You want to aggregate signals from multiple environments (on-prem, Kubernetes,
		etc.)

		Have one collector instance per signal type, for example, one dedicated to
		Prometheus metrics, one dedicated to Jaeger traces.


		- Simple to get started
		- Clear 1:1 mapping between application and collector

	- YouTube video [OpenTelemetry Collector Deployment Patterns][y-patterns]
	- KubeCon NA 2021 Talk [OpenTelemetry Collector Deployment Patterns][y-patterns]


		Cons:

		- Effort


		## Other information

		- GitHub repo [OpenTelemetry Collector Deployment Patterns][gh-patterns]

	- GitHub repo [OpenTelemetry Collector Deployment Patterns][gh-patterns]
	- [Repository with full configuration examples for different deployment patterns][gh-patterns]

inits Deployment contrib #2312

inits Deployment contrib #2312

Conversation

mhausenblas commented Feb 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cartermp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhausenblas commented Mar 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mx-psi Mar 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmitryax commented Mar 9, 2023 • edited Loading

mhausenblas commented Mar 13, 2023

svrnm commented Mar 13, 2023

mhausenblas commented Feb 9, 2023 •

edited

Loading

mx-psi Mar 9, 2023 •

edited

Loading

dmitryax commented Mar 9, 2023 •

edited

Loading