updated telemetry documentation including provider_schema_properties …

…information - telemetry is no longer part of plugin configuration but rather inside the service configuration
dikhan · Apr 22, 2020 · b2c5e53 · b2c5e53
1 parent 5ccd8f1
commit b2c5e53
Showing 1 changed file with 76 additions and 52 deletions.
diff --git a/docs/plugin_configuration_schema.md b/docs/plugin_configuration_schema.md
@@ -52,60 +52,8 @@ This is the root document object for the plugin configuration specification.
 Field Name | Type | Description
 ---|:---:|---
 version | `string` | **Required.** Specifies the OpenAPI plugin configuration spec version being used. The value MUST be `'1'`.
-telemetry | [Telemetry Object](#telemetry-object) | Telemetry configuration
 services | [Services Object](https://github.com/dikhan/terraform-provider-openapi/blob/master/docs/plugin_configuration_schema.md#services-object) | Specifies the service configurations
 
-##### Telemetry Object
-
-Describes the telemetry providers configurations.
-
-Field Name | Type | Description
----|:---:|---
-graphite | [Graphite Object](#graphite-object) | Graphite Telemetry configuration
-http_endpoint | [HTTP Endpoint Object](#http-endpoint-object) | HTTP Endpoint Telemetry configuration
-
-###### Graphite Object
-
-Describes the configuration for Graphite telemetry.
-
-Field Name | Type | Description
----|:---:|---
-host | `string` | **Required.** Graphite host to ship the metrics to
-port | `integer` | **Required.** Graphite port to connect to
-prefix | `string` | Some prefix to append to the metrics pushed to Graphite. If populated, metrics pushed to Graphite will be of the following form: `statsd.<prefix>.terraform....`. If the value is not provided, the metrics will not contain the prefix.
-
-The following metrics will be shipped to the corresponding configured Graphite host upon plugin execution:
-
-  - Terraform OpenAPI version used by the user: `statsd.<prefix>.terraform.openapi_plugin_version.*.total_runs` where * would contain the corresponding OpenAPI terraform plugin version used by the user (e,g: v0_25_0, etc)
-  - Service used by the user: `statsd.<prefix>.terraform.providers.*.total_runs` where * would contain the corresponding plugin name (service provider) used by the user (e,g: if the plugin name was terraform-provider-cdn the provider name in the metric would be 'cdn')
-
-###### HTTP Endpoint Object
-
-Describes the configuration for HTTP endpoint telemetry.
-
-Field Name | Type | Description
----|:---:|---
-url | `string` | **Required.** URL endpoint to where the metrics will be sent to (eg: https://my-app.com/v1/metrics)
-prefix | `string` | Some prefix to append to the metrics pushed to the http endpoint. If populated, metrics pushed to the endpoint will be of the following form: `<prefix>.terraform....`. If the value is not provided, the metrics will not contain the prefix.
-
-The following metrics will be shipped to the corresponding configured URL endpoint upon plugin execution:
-
-  - Terraform OpenAPI version used by the user: `<prefix>.terraform.openapi_plugin_version.*.total_runs` where * would contain the corresponding OpenAPI terraform plugin version used by the user (e,g: v0_25_0, etc).
-  - Service used by the user: `<prefix>.terraform.providers.*.total_runs` where * would contain the corresponding plugin name (service provider) used by the user (e,g: if the plugin name was terraform-provider-cdn the provider name in the metric would be 'cdn')
-
-The above will result into two separate POST HTTP requests to the corresponding configured URL passing in a JSON payload containing the `metric_type` with value 'IncCounter' and the `metric_name` being one of the above values. The 'IncCounter' value describes an increase of 1 in the corresponding counter metric, the consumer (eg: API) then will decide how to handle this information. The request will also contain a `User-Agent` header identifying the OpenAPI Terraform provider as the client.
-
-- Example of HTTP request sent to the HTTP endpoint increasing the `<prefix>.terraform.openapi_plugin_version.*.total_runs` counter:
-````
-curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":"<prefix>.terraform.openapi_plugin_version.0_26_0.total_runs"}' -H "Content-Type: application/json" -H "User-Agent: OpenAPI Terraform Provider/v0.26.0-b8364420eb450a34ff02e4c7832ad52165cd05b4 (darwin/amd64)"
-````  
-
-- Example of HTTP request sent to the HTTP endpoint increasing the `<prefix>.terraform.providers.*.total_runs` counter:
-
-````
-curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":"<prefix>.terraform.providers.cdn.total_runs"}' -H "Content-Type: application/json" -H "User-Agent: OpenAPI Terraform Provider/v0.26.0-b8364420eb450a34ff02e4c7832ad52165cd05b4 (darwin/amd64)"
-````
-
 ##### Services Object
 
 Holds the configuration for individual services
@@ -124,6 +72,7 @@ swagger-url | `string` | **Required.** Defines the location where the swagger do
 plugin_version | `string` | Defines the plugin version. If this value is specified (and it is not an empty string), the openapi plugin version executed must match this value; otherwise the validation will fail throwing an error at runtime. If the property is not set at all or the property is set with a value of empty string, then the default behaviour is that no validation will be performed.
 insecure_skip_verify | `string` | Defines whether a certificate verification should be performed when retrieving ```swagger-url``` from the server. This is **not recommended** for regular use and should only be set when the server hosting the swagger file is known and trusted but does not have a cert signed by the usually trusted CAs.
 schema_configuration | [][Schema Configuration Object](https://github.com/dikhan/terraform-provider-openapi/blob/master/docs/plugin_configuration_schema.md#schema-configuration-object) |  | Schema Configuration Object
+telemetry | [Telemetry Object](#telemetry-object) | Telemetry configuration
 
 ##### Schema Configuration Object
 
@@ -180,3 +129,78 @@ services:
     goa: 
       swagger-url: https://some-domain-where-swagger-is-served.com/swagger.yaml
 ````
+
+##### Telemetry Object
+
+Describes the telemetry providers configurations.
+
+Field Name | Type | Description
+---|:---:|---
+graphite | [Graphite Object](#graphite-object) | Graphite Telemetry configuration
+http_endpoint | [HTTP Endpoint Object](#http-endpoint-object) | HTTP Endpoint Telemetry configuration
+
+###### Graphite Object
+
+Describes the configuration for Graphite telemetry.
+
+Field Name | Type | Description
+---|:---:|---
+host | `string` | **Required.** Graphite host to ship the metrics to
+port | `integer` | **Required.** Graphite port to connect to
+prefix | `string` | Some prefix to append to the metrics pushed to Graphite. If populated, metrics pushed to Graphite will be of the following form: `statsd.<prefix>.terraform....`. If the value is not provided, the metrics will not contain the prefix.
+
+The following metrics will be shipped to the corresponding configured Graphite host upon plugin execution:
+
+  - Terraform OpenAPI version used by the user: `statsd.<prefix>.terraform.openapi_plugin_version.*.total_runs` where * would contain the corresponding OpenAPI terraform plugin version used by the user (e,g: v0_25_0, etc)
+  - Service used by the user: `statsd.<prefix>.terraform.providers.*.total_runs` where * would contain the corresponding plugin name (service provider) used by the user (e,g: if the plugin name was terraform-provider-cdn the provider name in the metric would be 'cdn')
+
+###### HTTP Endpoint Object
+
+Describes the configuration for HTTP endpoint telemetry.
+
+Field Name | Type | Description
+---|:---:|---
+url | `string` | **Required.** URL endpoint to where the metrics will be sent to (eg: https://my-app.com/v1/metrics). The endpoint must use HTTPs protocol.
+prefix | `string` | Some prefix to append to the metrics pushed to the http endpoint. If populated, metrics pushed to the endpoint will be of the following form: `<prefix>.terraform....`. If the value is not provided, the metrics will not contain the prefix. 
+provider_schema_properties | `[]string` | Defines what specific provider configuration properties and their values will be injected into metric API request headers. This is useful in cases where you need the specified provider configuration's properties as part of for instance the metric tags. Values must match a real property name in provider schema configuration.
+
+The following metrics will be shipped to the corresponding configured URL endpoint upon plugin execution:
+
+  - Terraform OpenAPI version used by the user: `<prefix>.terraform.openapi_plugin_version.total_runs` 
+  - Service used by the user: `<prefix>.terraform.providers.total_runs`
+
+The above will result into two separate POST HTTP requests to the corresponding configured URL passing in a JSON payload 
+containing the `metric_type` with value 'IncCounter' and the `metric_name` being one of the above values. The 'IncCounter' 
+value describes an increase of 1 in the corresponding counter metric, the consumer (eg: API) then will decide how to handle this 
+information. The request will also contain a `User-Agent` header identifying the OpenAPI Terraform provider as the client.
+
+- Example of HTTP request sent to the HTTP endpoint increasing the `<prefix>.terraform.openapi_plugin_version.total_runs` counter:
+````
+curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":"<prefix>.terraform.openapi_plugin_versiontotal_runs", "tags": ["openapi_plugin_version:0_25_0"]}' -H "Content-Type: application/json" -H "User-Agent: OpenAPI Terraform Provider/v0.26.0-b8364420eb450a34ff02e4c7832ad52165cd05b4 (darwin/amd64)"
+````  
+
+Note the specific OpenAPI terraform plugin version used is passed in the `tags` property (e,g: 0_25_0, etc).
+
+- Example of HTTP request sent to the HTTP endpoint increasing the `<prefix>.terraform.providers.total_runs` counter:
+
+````
+curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":"<prefix>.terraform.providers.total_runs", "tags": ["provider_name:cdn"]}' -H "Content-Type: application/json" -H "User-Agent: OpenAPI Terraform Provider/v0.26.0-b8364420eb450a34ff02e4c7832ad52165cd05b4 (darwin/amd64)"
+````
+
+Note the specific plugin name (service provider) used is passed in the `tags` property (e,g: if the plugin name was terraform-provider-cdn the provider name in the metric would be 'cdn')
+
+
+- Example of HTTP request submitting the `terraform.providers.total_runs` metric where the `provider_schema_properties` property is populated with one of the properties exposed by the provider configuration:
+
+````
+provider openapi {
+  billing_id = "some_id"
+}
+````
+
+````
+curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":"<prefix>.terraform.providers.total_runs", "tags": ["provider_name:cdn"]}' -H "billing_id: some_id" -H "Content-Type: application/json" -H "User-Agent: OpenAPI Terraform Provider/v0.26.0-b8364420eb450a34ff02e4c7832ad52165cd05b4 (darwin/amd64)"
+````
+
+Note the provider configuration property and its value is attached to the header (following the OpenAPI plugin behaviour when appending to
+the API requests the provider configuration properties) so the API will then be able to use this value for whatever it needs to.