From fa35150b911e30ecfdc74c17eb7ea6b7f4cf26d9 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Thu, 28 Jul 2022 14:06:26 -0400 Subject: [PATCH] website: Logging navigation adjustments, minor HTTP Transport page fixes (#1016) This adjusts the side navigation so Logging and Testing are more prominent and close to Debugging, which are similar in nature. --- website/data/plugin-sdk-nav-data.json | 116 ++++++++++-------- .../plugin/sdkv2/logging/http-transport.mdx | 7 +- 2 files changed, 63 insertions(+), 60 deletions(-) diff --git a/website/data/plugin-sdk-nav-data.json b/website/data/plugin-sdk-nav-data.json index d14ca45b88..855382810c 100644 --- a/website/data/plugin-sdk-nav-data.json +++ b/website/data/plugin-sdk-nav-data.json @@ -40,6 +40,68 @@ } ] }, + { + "title": "Logging", + "routes": [ + { + "title": "Overview", + "path": "logging" + }, + { + "title": "Writing Logs", + "href": "/plugin/log/writing" + }, + { + "title": "Filtering Logs", + "href": "/plugin/log/filtering" + }, + { + "title": "HTTP Transport", + "path": "logging/http-transport" + } + ] + }, + { + "title": "Testing", + "routes": [ + { "title": "Overview", "path": "testing" }, + { + "title": "Acceptance Testing", + "routes": [ + { + "title": "Overview", + "path": "testing/acceptance-tests" + }, + { + "title": "Test Cases", + "path": "testing/acceptance-tests/testcase" + }, + { + "title": "Test Steps", + "path": "testing/acceptance-tests/teststep" + }, + { + "title": "Sweepers", + "path": "testing/acceptance-tests/sweepers" + } + ] + }, + { + "title": "Testing API", + "path": "testing/testing-api", + "hidden": true + }, + { + "title": "Testing Patterns", + "path": "testing/testing-patterns", + "hidden": true + }, + { + "title": "Unit Testing", + "path": "testing/unit-testing" + } + ] + }, { "title": "Debugging Providers", "path": "debugging" }, { "title": "Upgrade Guides", @@ -95,59 +157,5 @@ "path": "best-practices/other-languages" } ] - }, - { - "title": "Logging", - "routes": [ - { - "title": "Overview", - "path": "logging" - }, - { - "title": "HTTP Transport", - "path": "logging/http-transport" - } - ] - }, - { - "title": "Testing", - "routes": [ - { "title": "Overview", "path": "testing" }, - { - "title": "Acceptance Testing", - "routes": [ - { - "title": "Overview", - "path": "testing/acceptance-tests" - }, - { - "title": "Test Cases", - "path": "testing/acceptance-tests/testcase" - }, - { - "title": "Test Steps", - "path": "testing/acceptance-tests/teststep" - }, - { - "title": "Sweepers", - "path": "testing/acceptance-tests/sweepers" - } - ] - }, - { - "title": "Testing API", - "path": "testing/testing-api", - "hidden": true - }, - { - "title": "Testing Patterns", - "path": "testing/testing-patterns", - "hidden": true - }, - { - "title": "Unit Testing", - "path": "testing/unit-testing" - } - ] } ] diff --git a/website/docs/plugin/sdkv2/logging/http-transport.mdx b/website/docs/plugin/sdkv2/logging/http-transport.mdx index 82db67eb93..89233ca259 100644 --- a/website/docs/plugin/sdkv2/logging/http-transport.mdx +++ b/website/docs/plugin/sdkv2/logging/http-transport.mdx @@ -12,7 +12,6 @@ We do not recommend using this original helper because it is designed to log the Instead, we recommend using the [terraform-plugin-log](https://www.terraform.io/plugin/log) library to produce logs for your provider. This library does not present the same security concerns and provides [log filtering](https://www.terraform.io/plugin/log/filtering) functionality. This page explains how to set up the new `RoundTripper()` helper to log HTTP Transactions with `terraform-plugin-log`. - # Setting Up Logging for HTTP Transactions The recommended logging helper for SDK is built on top of [terraform-plugin-log](https://www.terraform.io/plugin/log). This lets you leverage the features from our structured logging framework without having to write an entire implementation of `http.RoundTripper`. @@ -24,7 +23,6 @@ There are two functions inside `helper/logging` that target a specific logging s To set up HTTP transport, you must create the HTTP Client to use the new transport and then add logging configuration to the HTTP request context. - ### Creating the HTTP Client After you create the transport , you must use it to set up the `http.Client` for the provider. The following example sets up the client in `schema.Provider` `ConfigureContextFunc`. The client is identical to the default Golang `http.Client`, except it uses the new logging transport. @@ -47,7 +45,7 @@ func New() (*schema.Provider, error) { } } } - +``` ## Adding Context to HTTP Requests @@ -71,7 +69,6 @@ defer res.Body.Close() Use the [`(http.Request).WithContext()` method](https://pkg.go.dev/net/http#Request.WithContext) to set the context for the `http.Request` if the request is generated separately from where the `context.Context` is available. - ## HTTP Transaction Log Format The logging transport produces two log entries for each HTTP transaction: one for the request and one for the response. @@ -176,7 +173,6 @@ Each log contains the following information, which is represented as [fields](ht | `tf_http_res_version` | Response HTTP version | Ex. `"HTTP/2.0"` | Response | | (Other fields) | Request / Response headers. One field per header. If the header contains a single value, the log field value is set to that value. Otherwise, the field value is a slice of strings. | | Request / Response | - ## Filtering Sensitive Data To [filter logs](https://www.terraform.io/plugin/log/filtering), you must configure the `context.Context` before before it is added to the `http.Request`. @@ -200,7 +196,6 @@ if err != nil { defer res.Body.Close() ``` - # Links * [Plugin Development - Logging](https://www.terraform.io/plugin/log) - Learn more about the logging framework