Unverified Commit dcfb8557 authored by Harry Barber's avatar Harry Barber Committed by GitHub
Browse files

Add Instrumentation documentation (#1772) 

* Add documentation covering instrumentation approaches for Smithy Rust.

* Tweak the logging in the Pokemon service to better exemplify instrumentation.
    * Remove `TraceLayer` which violates sensitivity contract.
    * Switch to [Pretty](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/struct.Pretty.html) logs to better showcase the outputs.

* Update [Logging in the Presence of Sensitive Data](https://github.com/awslabs/smithy-rs/pull/1536) checklist.
* Rename `logging` module to `instrumentation` to improve coherence across struct names and documentation.
parent 7b96ae41

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerHttpSensitivityGenerator.kt

+21 −21
Original line number Diff line number Diff line
@@ -41,9 +41,9 @@ class StatusCodeSensitivity(private val sensitive: Boolean, runtimeConfig: Runti 
    /** Returns the type of the `MakeFmt`. */

    fun type(): Writable = writable {

        if (sensitive) {

            rustTemplate("#{SmithyHttpServer}::logging::MakeSensitive", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::MakeSensitive", *codegenScope)

        } else {

            rustTemplate("#{SmithyHttpServer}::logging::MakeIdentity", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::MakeIdentity", *codegenScope)

        }

    }
@@ -86,9 +86,9 @@ class LabelSensitivity(internal val labelIndexes: List<Int>, internal val greedy 


    /** Returns the type of the `MakeFmt`. */

    fun type(): Writable = if (hasRedactions()) writable {

        rustTemplate("#{SmithyHttpServer}::logging::sensitivity::uri::MakeLabel<fn(usize) -> bool>", *codegenScope)

        rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::uri::MakeLabel<fn(usize) -> bool>", *codegenScope)

    } else writable {

        rustTemplate("#{SmithyHttpServer}::logging::MakeIdentity", *codegenScope)

        rustTemplate("#{SmithyHttpServer}::instrumentation::MakeIdentity", *codegenScope)

    }



    /** Returns the value of the `GreedyLabel`. */
@@ -96,7 +96,7 @@ class LabelSensitivity(internal val labelIndexes: List<Int>, internal val greedy 
        if (greedyLabel != null) {

            rustTemplate(

                """

                Some(#{SmithyHttpServer}::logging::sensitivity::uri::GreedyLabel::new(${greedyLabel.segmentIndex}, ${greedyLabel.endOffset}))""",

                Some(#{SmithyHttpServer}::instrumentation::sensitivity::uri::GreedyLabel::new(${greedyLabel.segmentIndex}, ${greedyLabel.endOffset}))""",

                *codegenScope,

            )

        } else {
@@ -148,9 +148,9 @@ sealed class HeaderSensitivity( 
    /** Returns the type of the `MakeDebug`. */

    fun type(): Writable = writable {

        if (hasRedactions()) {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::headers::MakeHeaders<fn(&#{Http}::header::HeaderName) -> #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker>", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::headers::MakeHeaders<fn(&#{Http}::header::HeaderName) -> #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker>", *codegenScope)

        } else {

            rustTemplate("#{SmithyHttpServer}::logging::MakeIdentity", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::MakeIdentity", *codegenScope)

        }

    }
@@ -194,7 +194,7 @@ sealed class HeaderSensitivity( 
                        let name_match = #{NameMatch:W};



                        #{SuffixAndValue:W}

                        #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { key_suffix, value }

                        #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { key_suffix, value }

                    }

                } as fn(&_) -> _

                """,
@@ -240,9 +240,9 @@ sealed class QuerySensitivity( 
    /** Returns the type of the `MakeFmt`. */

    fun type(): Writable = writable {

        if (hasRedactions()) {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::uri::MakeQuery<fn(&str) -> #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker>", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::uri::MakeQuery<fn(&str) -> #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker>", *codegenScope)

        } else {

            rustTemplate("#{SmithyHttpServer}::logging::MakeIdentity", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::MakeIdentity", *codegenScope)

        }

    }
@@ -267,7 +267,7 @@ sealed class QuerySensitivity( 
                    |name: &str| {

                        let key = $allKeysSensitive;

                        let value = #{Value:W};

                        #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker { key, value }

                        #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker { key, value }

                    }

                } as fn(&_) -> _

                """,
@@ -296,7 +296,7 @@ data class MakeFmt( 
 * parts of the request/response HTTP as sensitive.

 *

 * These closures are provided to `RequestFmt` and `ResponseFmt` constructors, which in turn are provided to

 * `InstrumentedOperation` to configure logging. These structures can be found in `aws_smithy_http_server::logging`.

 * `InstrumentedOperation` to configure logging. These structures can be found in `aws_smithy_http_server::instrumentation`.

 *

 * See [Logging in the Presence of Sensitive Data](https://github.com/awslabs/smithy-rs/blob/main/design/src/rfcs/rfc0018_logging_sensitive.md)

 * for more details.
@@ -458,10 +458,10 @@ class ServerHttpSensitivityGenerator( 


    private fun defaultRequestFmt(): MakeFmt {

        val type = writable {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::DefaultRequestFmt", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::DefaultRequestFmt", *codegenScope)

        }

        val value = writable {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::RequestFmt::new()", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::RequestFmt::new()", *codegenScope)

        }

        return MakeFmt(type, value)

    }
@@ -483,9 +483,9 @@ class ServerHttpSensitivityGenerator( 
        val type = writable {

            rustTemplate(

                """

                #{SmithyHttpServer}::logging::sensitivity::RequestFmt<

                #{SmithyHttpServer}::instrumentation::sensitivity::RequestFmt<

                    #{HeaderType:W},

                    #{SmithyHttpServer}::logging::sensitivity::uri::MakeUri<

                    #{SmithyHttpServer}::instrumentation::sensitivity::uri::MakeUri<

                        #{LabelType:W},

                        #{QueryType:W}

                    >
@@ -498,18 +498,18 @@ class ServerHttpSensitivityGenerator( 
            )

        }



        val value = writable { rustTemplate("#{SmithyHttpServer}::logging::sensitivity::RequestFmt::new()", *codegenScope) } + headerSensitivity.setter() + labelSensitivity.setter() + querySensitivity.setters()

        val value = writable { rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::RequestFmt::new()", *codegenScope) } + headerSensitivity.setter() + labelSensitivity.setter() + querySensitivity.setters()



        return MakeFmt(type, value)

    }



    private fun defaultResponseFmt(): MakeFmt {

        val type = writable {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::DefaultResponseFmt", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::DefaultResponseFmt", *codegenScope)

        }



        val value = writable {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::ResponseFmt::new()", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::ResponseFmt::new()", *codegenScope)

        }

        return MakeFmt(type, value)

    }
@@ -527,7 +527,7 @@ class ServerHttpSensitivityGenerator( 


        val type = writable {

            rustTemplate(

                "#{SmithyHttpServer}::logging::sensitivity::ResponseFmt<#{HeaderType:W}, #{StatusType:W}>",

                "#{SmithyHttpServer}::instrumentation::sensitivity::ResponseFmt<#{HeaderType:W}, #{StatusType:W}>",

                "HeaderType" to headerSensitivity.type(),

                "StatusType" to statusCodeSensitivity.type(),

                *codegenScope,
@@ -535,7 +535,7 @@ class ServerHttpSensitivityGenerator( 
        }



        val value = writable {

            rustTemplate("#{SmithyHttpServer}::logging::sensitivity::ResponseFmt::new()", *codegenScope)

            rustTemplate("#{SmithyHttpServer}::instrumentation::sensitivity::ResponseFmt::new()", *codegenScope)

        } + headerSensitivity.setter() + statusCodeSensitivity.setter()



        return MakeFmt(type, value)

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationGenerator.kt

+1 −1
Original line number Diff line number Diff line
@@ -61,7 +61,7 @@ class ServerOperationGenerator( 
                type Error = #{Error:W};

            }



            impl #{SmithyHttpServer}::logging::sensitivity::Sensitivity for $operationName {

            impl #{SmithyHttpServer}::instrumentation::sensitivity::Sensitivity for $operationName {

                type RequestFmt = #{RequestType:W};

                type ResponseFmt = #{ResponseType:W};

codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerOperationRegistryGenerator.kt

+1 −1
Original line number Diff line number Diff line
@@ -338,7 +338,7 @@ ${operationImplementationStubs(operations)} 
                                let svc = #{ServerOperationHandler}::operation(registry.$operationName);

                                let request_fmt = #{RequestFmt:W};

                                let response_fmt = #{ResponseFmt:W};

                                let svc = #{SmithyHttpServer}::logging::InstrumentOperation::new(svc, "$operationName").request_fmt(request_fmt).response_fmt(response_fmt);

                                let svc = #{SmithyHttpServer}::instrumentation::InstrumentOperation::new(svc, "$operationName").request_fmt(request_fmt).response_fmt(response_fmt);

                                (#{Tower}::util::BoxCloneService::new(svc), $requestSpecVarName)

                                """,

                                "RequestFmt" to sensitivityGen.requestFmt().value,

codegen-server/src/test/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerHttpSensitivityGeneratorTest.kt

+16 −16
Original line number Diff line number Diff line
@@ -63,8 +63,8 @@ class ServerHttpSensitivityGeneratorTest { 
                rustTemplate(

                    """

                    let closure = #{Closure:W};

                    assert_eq!(closure("query_a"), #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker { key: false, value: false });

                    assert_eq!(closure("query_b"), #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker { key: false, value: true });

                    assert_eq!(closure("query_a"), #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker { key: false, value: false });

                    assert_eq!(closure("query_b"), #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker { key: false, value: true });

                    """,

                    "Closure" to querySensitivity.closure(),

                    *codegenScope,
@@ -110,7 +110,7 @@ class ServerHttpSensitivityGeneratorTest { 
                rustTemplate(

                    """

                    let closure = #{Closure:W};

                    assert_eq!(closure("wildcard"), #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker { key: true, value: true });

                    assert_eq!(closure("wildcard"), #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker { key: true, value: true });

                    """,

                    "Closure" to querySensitivity.closure(),

                    *codegenScope,
@@ -158,7 +158,7 @@ class ServerHttpSensitivityGeneratorTest { 
                rustTemplate(

                    """

                    let closure = #{Closure:W};

                    assert_eq!(closure("wildcard"), #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker { key: true, value: false });

                    assert_eq!(closure("wildcard"), #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker { key: true, value: false });

                    """,

                    "Closure" to querySensitivity.closure(),

                    *codegenScope,
@@ -206,7 +206,7 @@ class ServerHttpSensitivityGeneratorTest { 
                rustTemplate(

                    """

                    let closure = #{Closure:W};

                    assert_eq!(closure("wildcard"), #{SmithyHttpServer}::logging::sensitivity::uri::QueryMarker { key: false, value: true });

                    assert_eq!(closure("wildcard"), #{SmithyHttpServer}::instrumentation::sensitivity::uri::QueryMarker { key: false, value: true });

                    """,

                    "Closure" to querySensitivity.closure(),

                    *codegenScope,
@@ -284,9 +284,9 @@ class ServerHttpSensitivityGeneratorTest { 
                    """

                    let closure = #{Closure:W};

                    let name = #{Http}::header::HeaderName::from_static("header-a");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    let name = #{Http}::header::HeaderName::from_static("header-b");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: true, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: true, key_suffix: None });

                    """,

                    "Closure" to headerData.closure(),

                    *codegenScope,
@@ -332,11 +332,11 @@ class ServerHttpSensitivityGeneratorTest { 
                    """

                    let closure = #{Closure:W};

                    let name = #{Http}::header::HeaderName::from_static("prefix-a");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: true, key_suffix: Some(7) });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: true, key_suffix: Some(7) });

                    let name = #{Http}::header::HeaderName::from_static("prefix-b");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: true, key_suffix: Some(7) });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: true, key_suffix: Some(7) });

                    let name = #{Http}::header::HeaderName::from_static("other");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    """,

                    "Closure" to headerData.closure(),

                    *codegenScope,
@@ -415,11 +415,11 @@ class ServerHttpSensitivityGeneratorTest { 
                    """

                    let closure = #{Closure:W};

                    let name = #{Http}::header::HeaderName::from_static("prefix-a");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: false, key_suffix: Some(7) });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: false, key_suffix: Some(7) });

                    let name = #{Http}::header::HeaderName::from_static("prefix-b");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: false, key_suffix: Some(7) });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: false, key_suffix: Some(7) });

                    let name = #{Http}::header::HeaderName::from_static("other");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    """,

                    "Closure" to headerData.closure(),

                    *codegenScope,
@@ -469,11 +469,11 @@ class ServerHttpSensitivityGeneratorTest { 
                    """

                    let closure = #{Closure:W};

                    let name = #{Http}::header::HeaderName::from_static("prefix-a");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: true, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: true, key_suffix: None });

                    let name = #{Http}::header::HeaderName::from_static("prefix-b");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: true, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: true, key_suffix: None });

                    let name = #{Http}::header::HeaderName::from_static("other");

                    assert_eq!(closure(&name), #{SmithyHttpServer}::logging::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    assert_eq!(closure(&name), #{SmithyHttpServer}::instrumentation::sensitivity::headers::HeaderMarker { value: false, key_suffix: None });

                    """,

                    "Closure" to headerData.closure(),

                    *codegenScope,

design/src/docs/instrumentation.md

0 → 100644
+119 −0
Original line number Diff line number Diff line 
# Instrumentation



A Smithy Rust server uses the [`tracing`](https://github.com/tokio-rs/tracing) crate to provide instrumentation. The customer is responsible for setting up a [`Subscriber`](https://docs.rs/tracing/latest/tracing/subscriber/trait.Subscriber.html) in order to ingest and process [events](https://docs.rs/tracing/latest/tracing/struct.Event.html) - Smithy Rust makes no prescription on the choice of `Subscriber`. Common choices might include:



- [`tracing_subscriber::fmt`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/index.html) for printing to `stdout`.

- [`tracing-log`](https://crates.io/crates/tracing-log) to providing compatibility with the [`log`](https://crates.io/crates/log).



Events are emitted and [spans](https://docs.rs/tracing/latest/tracing/struct.Span.html) are opened by the `aws-smithy-http-server`, `aws-smithy-http-server-python`, and generated crate. The [default](https://docs.rs/tracing/latest/tracing/struct.Metadata.html) [target](https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.target) is always used



> The tracing macros default to using the module path where the span or event originated as the target, but it may be overridden.



and therefore spans and events be filtered using the [`EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) and/or [`Targets`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/targets/struct.Targets.html) filters with crate and module paths.



For example,



```bash

RUST_LOG=aws_smithy_http_server=warn,aws_smithy_http_server_python=error

```



and



```rust

let filter = filter::Targets::new().with_target("aws_smithy_http_server", Level::DEBUG);

```



In general, Smithy Rust is conservative when using high-priority log levels:



- ERROR

  - Fatal errors, resulting in the termination of the service.

  - Requires immediate remediation.

- WARN

  - Non-fatal errors, resulting in incomplete operation.

  - Indicates service misconfiguration, transient errors, or future changes in behavior.

  - Requires inspection and remediation.

- INFO

  - Informative events, which occur inside normal operating limits.

  - Used for large state transitions, e.g. startup/shutdown.

- DEBUG

  - Informative and sparse events, which occur inside normal operating limits.

  - Used to debug coarse-grained progress of service.

- TRACE

  - Informative and frequent events, which occur inside normal operating limits.

  - Used to debug fine-grained progress of service.



## Spans over the Request/Response lifecycle



Smithy Rust is built on top of [`tower`](https://github.com/tower-rs/tower), which means that middleware can be used to encompass different periods of the lifecycle of the request and response and identify them with a span.



An open-source example of such a middleware is [`TraceLayer`](https://docs.rs/tower-http/latest/tower_http/trace/struct.TraceLayer.html) provided by the [`tower-http`](https://docs.rs/tower-http/latest/tower_http/) crate.



Smithy provides an out-the-box middleware which:



- Opens a DEBUG level span, prior to request handling, including the operation name and request URI and headers.

- Emits a DEBUG level event, after to request handling, including the response headers and status code.



This is applied by default and can be enabled and disabled by filtering on `aws_smithy_http_server::logging`.



<!-- TODO: Link to it when the logging module is no longer `#[doc(hidden)]` -->



<!-- TODO: Document use of the `InstrumentExt` after the new service builder is released. -->



### Example



The Pokémon service example, located at `rust-runtime/aws-smithy-http-server/examples/pokemon-service`, sets up a `tracing` `Subscriber` as follows:



```rust

/// Setup `tracing::subscriber` to read the log level from RUST_LOG environment variable.

pub fn setup_tracing() {

    let format = tracing_subscriber::fmt::layer().pretty();

    let filter = EnvFilter::try_from_default_env()

        .or_else(|_| EnvFilter::try_new("info"))

        .unwrap();

    tracing_subscriber::registry().with(format).with(filter).init();

}

```



Running the Pokémon service example using



```bash

RUST_LOG=aws_smithy_http_server=debug,pokemon_service=debug cargo r

```



and then using `cargo t` to run integration tests against the server, yields the following logs:



```text

  2022-09-27T09:13:35.372517Z DEBUG aws_smithy_http_server::logging::service: response, headers: {"content-type": "application/json", "content-length": "17"}, status_code: 200 OK

    at /smithy-rs/rust-runtime/aws-smithy-http-server/src/logging/service.rs:47

    in aws_smithy_http_server::logging::service::request with operation: get_server_statistics, method: GET, uri: /stats, headers: {"host": "localhost:13734"}



  2022-09-27T09:13:35.374104Z DEBUG pokemon_service: attempting to authenticate storage user

    at pokemon-service/src/lib.rs:184

    in aws_smithy_http_server::logging::service::request with operation: get_storage, method: GET, uri: /pokedex/{redacted}, headers: {"passcode": "{redacted}", "host": "localhost:13734"}



  2022-09-27T09:13:35.374152Z DEBUG pokemon_service: authentication failed

    at pokemon-service/src/lib.rs:188

    in aws_smithy_http_server::logging::service::request with operation: get_storage, method: GET, uri: /pokedex/{redacted}, headers: {"passcode": "{redacted}", "host": "localhost:13734"}



  2022-09-27T09:13:35.374230Z DEBUG aws_smithy_http_server::logging::service: response, headers: {"content-type": "application/json", "x-amzn-errortype": "NotAuthorized", "content-length": "2"}, status_code: 401 Unauthorized

    at /smithy-rs/rust-runtime/aws-smithy-http-server/src/logging/service.rs:47

    in aws_smithy_http_server::logging::service::request with operation: get_storage, method: GET, uri: /pokedex/{redacted}, headers: {"passcode": "{redacted}", "host": "localhost:13734"}

```



## Interactions with Sensitivity



Instrumentation interacts with Smithy's [sensitive trait](https://awslabs.github.io/smithy/2.0/spec/documentation-traits.html#sensitive-trait).



> Sensitive data MUST NOT be exposed in things like exception messages or log output. Application of this trait SHOULD NOT affect wire logging (i.e., logging of all data transmitted to and from servers or clients).



For this reason, Smithy runtime will never use `tracing` to emit events or open spans that include any sensitive data. This means that the customer can ingest all logs from `aws-smithy-http-server` and `aws-smithy-http-server-*` without fear of violating the sensitive trait.



The Smithy runtime will not, and cannot, prevent the customer violating the sensitive trait within the operation handlers and custom middleware. It is the responsibility of the customer to not violate the sensitive contract of their own model, care must be taken.



Smithy shapes can be sensitive while being coupled to the HTTP request/responses via the [HTTP binding traits](https://awslabs.github.io/smithy/2.0/spec/http-bindings.html). This poses a risk when ingesting events which naively capture request/response information. The instrumentation middleware provided by Smithy Rust respects the sensitive trait and will replace sensitive data in its span and event with `{redacted}`. This feature can be seen in the [Example](#example) above. For debugging purposes these redactions can be prevented using the `aws-smithy-http-server` feature flag, `unredacted-logging`.



Some examples of inadvertently leaking sensitive information:



- Ingesting tracing events and spans from third-party crates which do not respect sensitivity.

  - An concrete example of this would be enabling events from `hyper` or `tokio`.

- Applying middleware which ingests events including HTTP payloads or any other part of the HTTP request/response which can be bound.