From 3d92547bc360abe2e5df0118da189609e8f9909b Mon Sep 17 00:00:00 2001 From: Spencer Gilbert Date: Thu, 11 Aug 2022 11:46:13 -0400 Subject: [PATCH] docs(opentelemetry source): Refresh documentation and examples (#13921) * docs(opentelemetry source): Refresh documentation and examples * +cue fmt * allow multiple examples, and add multiple examples * add configuration_example * +tls options * +cue-fmt * +example feedback --- .../configuration/sources/opentelemetry.md | 2 +- website/cue/reference.cue | 2 +- .../components/sources/opentelemetry.cue | 110 +++++++++++++----- website/cue/reference/urls.cue | 3 +- 4 files changed, 88 insertions(+), 29 deletions(-) diff --git a/website/content/en/docs/reference/configuration/sources/opentelemetry.md b/website/content/en/docs/reference/configuration/sources/opentelemetry.md index 5d6b7a49d20bd..e89dea0e891cd 100644 --- a/website/content/en/docs/reference/configuration/sources/opentelemetry.md +++ b/website/content/en/docs/reference/configuration/sources/opentelemetry.md @@ -1,6 +1,6 @@ --- title: OpenTelemetry -description: Receive [OpenTelemetry](https://opentelemetry.io/) data directly from a SDK or an OpenTelemetry Collector. +description: Receive [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/) data through gRPC or HTTP. kind: source layout: component tags: ["opentelemetry", "component", "source", "logs"] diff --git a/website/cue/reference.cue b/website/cue/reference.cue index d7e8e6df6dade..34e1a83456ef9 100644 --- a/website/cue/reference.cue +++ b/website/cue/reference.cue @@ -529,7 +529,7 @@ _values: { // `examples` clarify values through examples. This should be used // when examples cannot be derived from the `default` or `enum` // options. - examples: [#Object] | *[] + examples: [#Object, ...#Object] | *[] // `options` represent the child options for this option. options: #Schema diff --git a/website/cue/reference/components/sources/opentelemetry.cue b/website/cue/reference/components/sources/opentelemetry.cue index d990cfeeeeff0..e4a8412450a76 100644 --- a/website/cue/reference/components/sources/opentelemetry.cue +++ b/website/cue/reference/components/sources/opentelemetry.cue @@ -6,10 +6,6 @@ components: sources: opentelemetry: { title: "OpenTelemetry" - description: """ - Collect OpenTelemetry data over gRPC and HTTP (currently, only logs are supported). - """ - classes: { commonly_used: false delivery: "at_least_once" @@ -42,7 +38,11 @@ components: sources: opentelemetry: { support: { requirements: [] - warnings: [] + warnings: [ + """ + The `opentelemetry` source only supports log events at this time. + """, + ] notices: [] } @@ -98,6 +98,32 @@ components: sources: opentelemetry: { } } + configuration_examples: [ + { + title: "OTLP Defaults" + configuration: { + opentelemetry: { + grpc: { + address: "0.0.0.0:4317" + tls: { + enabled: true + crt_file: "/etc/ssl/certs/vector.pem" + key_file: "/etc/ssl/private/vector.key" + } + } + http: { + address: "0.0.0.0:4318" + tls: { + enabled: true + crt_file: "/etc/ssl/certs/vector.pem" + key_file: "/etc/ssl/private/vector.key" + } + } + } + } + }, + ] + outputs: [ { name: "logs" @@ -109,14 +135,29 @@ components: sources: opentelemetry: { output: { logs: event: { - description: "An individual event from a batch of events received through a gRPC request sent by OpenTelemetry SDK" + description: "An individual log event from a batch of events received through an OTLP request" fields: { attributes: { description: "Attributes that describe the specific event occurrence." required: false common: true type: object: { - examples: [{"k1": "v1"}] + examples: [ + { + "http.status.code": 500 + "http.url": "http://example.com" + "my.custom.application.tag": "hello" + }, + { + "http.scheme": "https" + "http.host": "donut.mycie.com" + "http.target": "/order" + "http.method": "post" + "http.status_code": 500 + "http.flavor": "1.1" + "http.user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36" + }, + ] } } resources: { @@ -124,7 +165,16 @@ components: sources: opentelemetry: { required: false common: true type: object: { - examples: [{"k1": "v1"}] + examples: [ + { + "service.name": "donut_shop" + "service.version": "2.0.0" + "k8s.pod.uid": "1138528c-c36e-11e9-a1a7-42010a800198" + }, + { + "container.name": "vector" + }, + ] } } message: { @@ -133,7 +183,7 @@ components: sources: opentelemetry: { common: true type: string: { default: null - examples: ["hello world"] + examples: ["20200415T072306-0700 INFO I like donuts"] } } trace_id: { @@ -142,7 +192,7 @@ components: sources: opentelemetry: { common: true type: string: { default: null - examples: ["37e7518fe2e2fcaf22b41c2dac059221"] + examples: ["66346462623365646437363566363230"] } } span_id: { @@ -151,17 +201,21 @@ components: sources: opentelemetry: { common: true type: string: { default: null - examples: ["05abe7510db73b88"] + examples: ["43222c2d51a7abe3"] } } severity_number: { - description: "Numerical value of the severity. Smaller numerical values correspond to less severe events (such as debug events), larger numerical values correspond to more severe events (such as errors and critical events)." - required: false - common: true + description: """ + Numerical value of the severity. + + Smaller numerical values correspond to less severe events (such as debug events), larger numerical values correspond to more severe events (such as errors and critical events). + """ + required: false + common: true type: uint: { default: null unit: null - examples: [9] + examples: [3, 9, 17, 24] } } severity_text: { @@ -170,7 +224,7 @@ components: sources: opentelemetry: { common: true type: string: { default: null - examples: ["info"] + examples: ["TRACE3", "INFO", "ERROR", "FATAL4"] } } flags: { @@ -183,18 +237,22 @@ components: sources: opentelemetry: { } } timestamp: { - description: "The UTC Datetime when the event occurred." - required: true - type: uint: { - unit: null - } + description: """ + The UTC Datetime when the event occurred. If this value is unset, or `0`, it will be set to the `observed_timestamp` field. + + This field is converted from the `time_unix_nano` Protobuf field. + """ + required: true + type: timestamp: {} } observed_timestamp: { - description: "The UTC Datetime when the event was observed by the collection system." - required: true - type: uint: { - unit: null - } + description: """ + The UTC Datetime when the event was observed by the collection system. If this value is unset, or `0`, it will be set to the current time. + + This field is converted from the `observed_time_unix_nano` Protobuf field. + """ + required: true + type: timestamp: {} } dropped_attributes_count: { description: "Counts for attributes dropped due to collection limits." diff --git a/website/cue/reference/urls.cue b/website/cue/reference/urls.cue index a6737beaa4c65..5068451243bff 100644 --- a/website/cue/reference/urls.cue +++ b/website/cue/reference/urls.cue @@ -362,7 +362,8 @@ urls: { nixos: "https://nixos.org/" nixpkgs_9682: "\(github)/NixOS/nixpkgs/issues/9682" openssl: "https://www.openssl.org/" - opentelemetry: "https://opentelemetry.io/" + opentelemetry: "https://opentelemetry.io" + opentelemetry_protocol: "\(opentelemetry)/docs/reference/specification/protocol/otlp/" order_of_ops: "\(wikipedia)/wiki/Order_of_operations" papertrail: "https://www.papertrail.com/" papertrail_syslog: "https://help.papertrailapp.com/kb/how-it-works/http-api/#submitting-log-messages"