Skip to content

Commit

Permalink
website: Logging navigation adjustments, minor HTTP Transport page fi…
Browse files Browse the repository at this point in the history
…xes (#1016)

This adjusts the side navigation so Logging and Testing are more prominent and close to Debugging, which are similar in nature.
  • Loading branch information
bflad committed Jul 28, 2022
1 parent 92520a9 commit fa35150
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 60 deletions.
116 changes: 62 additions & 54 deletions website/data/plugin-sdk-nav-data.json
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
}
]
}
]
7 changes: 1 addition & 6 deletions website/docs/plugin/sdkv2/logging/http-transport.mdx
Expand Up @@ -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`.
Expand All @@ -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.
Expand All @@ -47,7 +45,7 @@ func New() (*schema.Provider, error) {
}
}
}

```

## Adding Context to HTTP Requests

Expand All @@ -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.
Expand Down Expand Up @@ -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`.
Expand All @@ -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
Expand Down

0 comments on commit fa35150

Please sign in to comment.