docs(humio_metrics sink, humio_logs sink): Use generated docs for con…

…figuration (vectordotdev#16211) * Use generated docs Signed-off-by: Stephen Wakely <[email protected]> * More examples Signed-off-by: Stephen Wakely <[email protected]> * Responding to feedback Signed-off-by: Stephen Wakely <[email protected]> * Update endpoint docs Signed-off-by: Stephen Wakely <[email protected]> * Fixed tests Signed-off-by: Stephen Wakely <[email protected]> * Remove quotes from url Signed-off-by: Stephen Wakely <[email protected]> * generated docs Signed-off-by: Stephen Wakely <[email protected]> --------- Signed-off-by: Stephen Wakely <[email protected]>
bderrly · Feb 3, 2023 · 0861774 · 0861774
1 parent 364c9d1
commit 0861774
Show file tree

Hide file tree

Showing 7 changed files with 111 additions and 37 deletions.
diff --git a/src/sinks/humio/logs.rs b/src/sinks/humio/logs.rs
@@ -21,19 +21,33 @@ use crate::{
     tls::TlsConfig,
 };
 
-const HOST: &str = "https://cloud.humio.com";
+pub(super) const HOST: &str = "https://cloud.humio.com";
 
 /// Configuration for the `humio_logs` sink.
 #[configurable_component(sink("humio_logs"))]
 #[derive(Clone, Debug)]
 #[serde(deny_unknown_fields)]
 pub struct HumioLogsConfig {
     /// The Humio ingestion token.
+    #[configurable(metadata(
+        docs::examples = "${HUMIO_TOKEN}",
+        docs::examples = "A94A8FE5CCB19BA61C4C08"
+    ))]
     pub(super) token: SensitiveString,
 
     /// The base URL of the Humio instance.
+    ///
+    /// The scheme (`http` or `https`) must be specified. No path should be included since the paths defined
+    /// by the [`Splunk`][splunk] api are used.
+    ///
+    /// [splunk]: https://docs.splunk.com/Documentation/Splunk/8.0.0/Data/HECRESTendpoints
     #[serde(alias = "host")]
-    pub(super) endpoint: Option<String>,
+    #[serde(default = "default_endpoint")]
+    #[configurable(metadata(
+        docs::examples = "http://127.0.0.1",
+        docs::examples = "https://example.com",
+    ))]
+    pub(super) endpoint: String,
 
     /// The source of events sent to this sink.
     ///
@@ -46,6 +60,11 @@ pub struct HumioLogsConfig {
     /// The type of events sent to this sink. Humio uses this as the name of the parser to use to ingest the data.
     ///
     /// If unset, Humio will default it to none.
+    #[configurable(metadata(
+        docs::examples = "json",
+        docs::examples = "none",
+        docs::examples = "{{ event_type }}"
+    ))]
     pub(super) event_type: Option<Template>,
 
     /// Overrides the name of the log field used to grab the hostname to send to Humio.
@@ -76,6 +95,7 @@ pub struct HumioLogsConfig {
     ///
     /// [humio_data_format]: https://docs.humio.com/integrations/data-shippers/hec/#format-of-data
     #[serde(default)]
+    #[configurable(metadata(docs::examples = "{{ host }}", docs::examples = "custom_index"))]
     pub(super) index: Option<Template>,
 
     #[configurable(derived)]
@@ -94,8 +114,6 @@ pub struct HumioLogsConfig {
     pub(super) tls: Option<TlsConfig>,
 
     /// Overrides the name of the log field used to grab the nanosecond-enabled timestamp to send to Humio.
-    ///
-    /// By default, `@timestamp.nanos` is used.
     #[serde(default = "timestamp_nanos_key")]
     pub(super) timestamp_nanos_key: Option<String>,
 
@@ -116,6 +134,10 @@ pub struct HumioLogsConfig {
     pub(super) timestamp_key: String,
 }
 
+fn default_endpoint() -> String {
+    HOST.to_string()
+}
+
 pub fn timestamp_nanos_key() -> Option<String> {
     Some("@timestamp.nanos".to_string())
 }
@@ -124,7 +146,7 @@ impl GenerateConfig for HumioLogsConfig {
     fn generate_config() -> toml::Value {
         toml::Value::try_from(Self {
             token: "${HUMIO_TOKEN}".to_owned().into(),
-            endpoint: None,
+            endpoint: default_endpoint(),
             source: None,
             encoding: JsonSerializerConfig::default().into(),
             event_type: None,
@@ -160,11 +182,9 @@ impl SinkConfig for HumioLogsConfig {
 
 impl HumioLogsConfig {
     fn build_hec_config(&self) -> HecLogsSinkConfig {
-        let endpoint = self.endpoint.clone().unwrap_or_else(|| HOST.to_string());
-
         HecLogsSinkConfig {
             default_token: self.token.clone(),
-            endpoint,
+            endpoint: self.endpoint.clone(),
             host_key: self.host_key.clone(),
             indexed_fields: self.indexed_fields.clone(),
             index: self.index.clone(),
@@ -354,7 +374,7 @@ mod integration_tests {
 
         HumioLogsConfig {
             token: token.to_string().into(),
-            endpoint: Some(humio_address()),
+            endpoint: humio_address(),
             source: None,
             encoding: JsonSerializerConfig::default().into(),
             event_type: None,

diff --git a/src/sinks/humio/metrics.rs b/src/sinks/humio/metrics.rs
@@ -7,7 +7,10 @@ use vector_common::sensitive_string::SensitiveString;
 use vector_config::configurable_component;
 use vector_core::{sink::StreamSink, transform::Transform};
 
-use super::{host_key, logs::HumioLogsConfig};
+use super::{
+    host_key,
+    logs::{HumioLogsConfig, HOST},
+};
 use crate::{
     config::{
         AcknowledgementsConfig, GenerateConfig, Input, SinkConfig, SinkContext, TransformConfig,
@@ -40,11 +43,25 @@ pub struct HumioMetricsConfig {
     transform: MetricToLogConfig,
 
     /// The Humio ingestion token.
+    #[configurable(metadata(
+        docs::examples = "${HUMIO_TOKEN}",
+        docs::examples = "A94A8FE5CCB19BA61C4C08"
+    ))]
     token: SensitiveString,
 
     /// The base URL of the Humio instance.
+    ///
+    /// The scheme (`http` or `https`) must be specified. No path should be included since the paths defined
+    /// by the [`Splunk`][splunk] api are used.
+    ///
+    /// [splunk]: https://docs.splunk.com/Documentation/Splunk/8.0.0/Data/HECRESTendpoints
     #[serde(alias = "host")]
-    pub(super) endpoint: Option<String>,
+    #[serde(default = "default_endpoint")]
+    #[configurable(metadata(
+        docs::examples = "http://127.0.0.1",
+        docs::examples = "https://example.com",
+    ))]
+    pub(super) endpoint: String,
 
     /// The source of events sent to this sink.
     ///
@@ -54,6 +71,11 @@ pub struct HumioMetricsConfig {
     /// The type of events sent to this sink. Humio uses this as the name of the parser to use to ingest the data.
     ///
     /// If unset, Humio will default it to none.
+    #[configurable(metadata(
+        docs::examples = "json",
+        docs::examples = "none",
+        docs::examples = "{{ event_type }}"
+    ))]
     event_type: Option<Template>,
 
     /// Overrides the name of the log field used to grab the hostname to send to Humio.
@@ -84,6 +106,7 @@ pub struct HumioMetricsConfig {
     ///
     /// [humio_data_format]: https://docs.humio.com/integrations/data-shippers/hec/#format-of-data
     #[serde(default)]
+    #[configurable(metadata(docs::examples = "{{ host }}", docs::examples = "custom_index"))]
     index: Option<Template>,
 
     #[configurable(derived)]
@@ -110,6 +133,10 @@ pub struct HumioMetricsConfig {
     acknowledgements: AcknowledgementsConfig,
 }
 
+fn default_endpoint() -> String {
+    HOST.to_string()
+}
+
 impl GenerateConfig for HumioMetricsConfig {
     fn generate_config() -> toml::Value {
         toml::from_str(indoc! {r#"
@@ -225,15 +252,15 @@ mod tests {
         "#})
         .unwrap();
 
-        assert_eq!(Some("https://localhost:9200/".to_string()), config.endpoint);
+        assert_eq!("https://localhost:9200/".to_string(), config.endpoint);
         let (config, _) = load_sink::<HumioMetricsConfig>(indoc! {r#"
             token = "atoken"
             batch.max_events = 1
             host = "https://localhost:9200/"
         "#})
         .unwrap();
 
-        assert_eq!(Some("https://localhost:9200/".to_string()), config.endpoint);
+        assert_eq!("https://localhost:9200/".to_string(), config.endpoint);
     }
 
     #[tokio::test]
@@ -247,8 +274,7 @@ mod tests {
         let addr = test_util::next_addr();
         // Swap out the endpoint so we can force send it
         // to our local server
-        let endpoint = format!("http://{}", addr);
-        config.endpoint = Some(endpoint.clone());
+        config.endpoint = format!("http://{}", addr);
 
         let (sink, _) = config.build(cx).await.unwrap();
 
@@ -314,8 +340,7 @@ mod tests {
         let addr = test_util::next_addr();
         // Swap out the endpoint so we can force send it
         // to our local server
-        let endpoint = format!("http://{}", addr);
-        config.endpoint = Some(endpoint.clone());
+        config.endpoint = format!("http://{}", addr);
 
         let (sink, _) = config.build(cx).await.unwrap();
 

diff --git a/website/cue/reference/components/sinks/base/humio_logs.cue b/website/cue/reference/components/sinks/base/humio_logs.cue
@@ -200,9 +200,19 @@ base: components: sinks: humio_logs: configuration: {
 		}
 	}
 	endpoint: {
-		description: "The base URL of the Humio instance."
-		required:    false
-		type: string: {}
+		description: """
+			The base URL of the Humio instance.
+
+			The scheme (`http` or `https`) must be specified. No path should be included since the paths defined
+			by the [`Splunk`][splunk] api are used.
+
+			[splunk]: https://docs.splunk.com/Documentation/Splunk/8.0.0/Data/HECRESTendpoints
+			"""
+		required: false
+		type: string: {
+			default: "https://cloud.humio.com"
+			examples: ["http://127.0.0.1", "https://example.com"]
+		}
 	}
 	event_type: {
 		description: """
@@ -211,7 +221,10 @@ base: components: sinks: humio_logs: configuration: {
 			If unset, Humio will default it to none.
 			"""
 		required: false
-		type: string: syntax: "template"
+		type: string: {
+			examples: ["json", "none", "{{ event_type }}"]
+			syntax: "template"
+		}
 	}
 	host_key: {
 		description: """
@@ -237,7 +250,10 @@ base: components: sinks: humio_logs: configuration: {
 			[humio_data_format]: https://docs.humio.com/integrations/data-shippers/hec/#format-of-data
 			"""
 		required: false
-		type: string: syntax: "template"
+		type: string: {
+			examples: ["{{ host }}", "custom_index"]
+			syntax: "template"
+		}
 	}
 	indexed_fields: {
 		description: """
@@ -419,12 +435,8 @@ base: components: sinks: humio_logs: configuration: {
 		type: string: default: "timestamp"
 	}
 	timestamp_nanos_key: {
-		description: """
-			Overrides the name of the log field used to grab the nanosecond-enabled timestamp to send to Humio.
-
-			By default, `@timestamp.nanos` is used.
-			"""
-		required: false
+		description: "Overrides the name of the log field used to grab the nanosecond-enabled timestamp to send to Humio."
+		required:    false
 		type: string: default: "@timestamp.nanos"
 	}
 	tls: {
@@ -515,6 +527,6 @@ base: components: sinks: humio_logs: configuration: {
 	token: {
 		description: "The Humio ingestion token."
 		required:    true
-		type: string: {}
+		type: string: examples: ["${HUMIO_TOKEN}", "A94A8FE5CCB19BA61C4C08"]
 	}
 }
diff --git a/website/cue/reference/components/sinks/base/humio_metrics.cue b/website/cue/reference/components/sinks/base/humio_metrics.cue
@@ -84,9 +84,19 @@ base: components: sinks: humio_metrics: configuration: {
 		}
 	}
 	endpoint: {
-		description: "The base URL of the Humio instance."
-		required:    false
-		type: string: {}
+		description: """
+			The base URL of the Humio instance.
+
+			The scheme (`http` or `https`) must be specified. No path should be included since the paths defined
+			by the [`Splunk`][splunk] api are used.
+
+			[splunk]: https://docs.splunk.com/Documentation/Splunk/8.0.0/Data/HECRESTendpoints
+			"""
+		required: false
+		type: string: {
+			default: "https://cloud.humio.com"
+			examples: ["http://127.0.0.1", "https://example.com"]
+		}
 	}
 	event_type: {
 		description: """
@@ -95,7 +105,10 @@ base: components: sinks: humio_metrics: configuration: {
 			If unset, Humio will default it to none.
 			"""
 		required: false
-		type: string: syntax: "template"
+		type: string: {
+			examples: ["json", "none", "{{ event_type }}"]
+			syntax: "template"
+		}
 	}
 	host_key: {
 		description: """
@@ -133,7 +146,10 @@ base: components: sinks: humio_metrics: configuration: {
 			[humio_data_format]: https://docs.humio.com/integrations/data-shippers/hec/#format-of-data
 			"""
 		required: false
-		type: string: syntax: "template"
+		type: string: {
+			examples: ["{{ host }}", "custom_index"]
+			syntax: "template"
+		}
 	}
 	indexed_fields: {
 		description: """
@@ -428,6 +444,6 @@ base: components: sinks: humio_metrics: configuration: {
 	token: {
 		description: "The Humio ingestion token."
 		required:    true
-		type: string: {}
+		type: string: examples: ["${HUMIO_TOKEN}", "A94A8FE5CCB19BA61C4C08"]
 	}
 }
diff --git a/website/cue/reference/components/sinks/humio.cue b/website/cue/reference/components/sinks/humio.cue
@@ -19,6 +19,7 @@ components: sinks: _humio: {
 	}
 
 	features: {
+		auto_generated:   true
 		acknowledgements: true
 		healthcheck: enabled: true
 		send: {

diff --git a/website/cue/reference/components/sinks/humio_logs.cue b/website/cue/reference/components/sinks/humio_logs.cue
@@ -14,7 +14,7 @@ components: sinks: humio_logs: {
 	classes:       sinks._humio.classes
 	features:      sinks._humio.features
 	support:       sinks._humio.support
-	configuration: sinks._humio.configuration
+	configuration: base.components.sinks.humio_logs.configuration
 	telemetry:     sinks._humio.telemetry
 
 	input: {

diff --git a/website/cue/reference/components/sinks/humio_metrics.cue b/website/cue/reference/components/sinks/humio_metrics.cue
@@ -6,7 +6,7 @@ components: sinks: humio_metrics: {
 	classes:       sinks._humio.classes
 	features:      sinks._humio.features
 	support:       sinks._humio.support
-	configuration: sinks._humio.configuration
+	configuration: base.components.sinks.humio_metrics.configuration
 	telemetry:     sinks._humio.telemetry
 
 	input: {