From b2c5e53d66b704a2159f2f854bcd818cc71636a5 Mon Sep 17 00:00:00 2001 From: dikhan Date: Wed, 22 Apr 2020 12:55:25 -0700 Subject: [PATCH] updated telemetry documentation including provider_schema_properties information - telemetry is no longer part of plugin configuration but rather inside the service configuration --- docs/plugin_configuration_schema.md | 128 +++++++++++++++++----------- 1 file changed, 76 insertions(+), 52 deletions(-) diff --git a/docs/plugin_configuration_schema.md b/docs/plugin_configuration_schema.md index 2e296113f..bc7cdee59 100644 --- 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..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..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..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: `.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: `.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: `.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 `.terraform.openapi_plugin_version.*.total_runs` counter: -```` -curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":".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 `.terraform.providers.*.total_runs` counter: - -```` -curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":".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..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..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..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: `.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: `.terraform.openapi_plugin_version.total_runs` + - Service used by the user: `.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 `.terraform.openapi_plugin_version.total_runs` counter: +```` +curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":".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 `.terraform.providers.total_runs` counter: + +```` +curl -X POST https://my-app.com/v1/metrics -d '{"metric_type": "IncCounter", "metric_name":".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":".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. \ No newline at end of file