V4 Updates for Metrics, Tracing and Security (#336)

* Update Cloud Foundry actuator/integration
---------

Co-authored-by: Bart Koelman <[email protected]>

api/v4/bootstrap/index.md

@@ -4,7 +4,7 @@ To improve the Steeltoe developer experience, this feature allows the configurat
 
 Get started by adding a reference to the AutoConfiguration package (you may want to add other Steeltoe references at this point too, see [the table below](#supported-steeltoe-packages) for the full list of what's supported):
 
-```
+```shell
 dotnet add package Steeltoe.Bootstrap.AutoConfiguration
 ```
 
@@ -36,7 +36,7 @@ builder.AddSteeltoe();
 | [Dynamic Console Logging](../logging/dynamic-console-logging.md) | `Steeltoe.Logging.DynamicConsole` | N/A |
 | [Dynamic Serilog Logging](../logging/dynamic-serilog-logging.md) | `Steeltoe.Logging.DynamicSerilog` | N/A |
 | [Actuators](../management/index.md) | `Steeltoe.Management.Endpoint` | N/A |
-| [Distributed Tracing](../tracing/index.md) | `Steeltoe.Management.Tracing` | Required: OpenTelemetry Exporter (Zipkin, OTLP) |
+| [Distributed Tracing](../tracing/index.md) | `Steeltoe.Management.Tracing` | N/A |
 
 [^1]: Individual connector clients will only be configured if a corresponding supported driver NuGet package reference is also included.
 

api/v4/configuration/config-server-provider.md

@@ -6,7 +6,7 @@ The Spring Cloud Config Server is an application configuration service that give
 
 To gain a better understanding of the Spring Cloud Config Server, you should read the [Spring Cloud Config documentation](https://spring.io/projects/spring-cloud-config).
 
-In addition to the Quick Start provided later, you can refer to the [Steeltoe ConfigurationProviders](https://github.com/SteeltoeOSS/Samples/tree/latest/Configuration/src/ConfigurationProviders) sample application when you need to understand how to use this provider.
+In addition to the Quick Start provided later, you can refer to the [Steeltoe ConfigurationProviders](https://github.com/SteeltoeOSS/Samples/tree/main/Configuration/src/ConfigurationProviders) sample application when you need to understand how to use this provider.
 
 ## Usage
 

api/v4/connectors/cosmosdb.md

@@ -118,7 +118,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `CosmosClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/CosmosDb.
+A complete sample app that uses `CosmosClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/CosmosDb.
 
 ## Cloud Foundry
 

api/v4/connectors/microsoft-sql-server.md

@@ -135,7 +135,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/SqlServerEFCore.
+A complete sample app that uses Entity Framework Core with SQL Server is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/SqlServerEFCore.
 
 ## Cloud Foundry
 

api/v4/connectors/mongodb.md

@@ -96,7 +96,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `IMongoClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MongoDb.
+A complete sample app that uses `IMongoClient` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb.
 
 ## Cloud Foundry
 
@@ -121,4 +121,4 @@ cf restage myApp
 This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec).
 It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html).
 
-For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MongoDb#running-on-tanzu-application-platform-tap.
+For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MongoDb#running-on-tanzu-application-platform-tap.

api/v4/connectors/mysql.md

@@ -86,7 +86,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `MySqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MySql.
+A complete sample app that uses `MySqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql.
 
 ### Use Entity Framework Core
 
@@ -139,7 +139,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses Entity Framework Core with MySQL is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MySqlEFCore.
+A complete sample app that uses Entity Framework Core with MySQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySqlEFCore.
 
 ## Cloud Foundry
 
@@ -166,4 +166,4 @@ cf restage myApp
 This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec).
 It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html).
 
-For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/MySql#running-on-tanzu-application-platform-tap.
+For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/MySql#running-on-tanzu-application-platform-tap.

api/v4/connectors/postgresql.md

@@ -84,7 +84,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `NpgsqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/PostgreSql.
+A complete sample app that uses `NpgsqlConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql.
 
 ### Use Entity Framework Core
 
@@ -137,7 +137,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses Entity Framework Core with PostgreSQL is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/PostgreSqlEFCore.
+A complete sample app that uses Entity Framework Core with PostgreSQL is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSqlEFCore.
 
 ## Cloud Foundry
 
@@ -163,4 +163,4 @@ cf restage myApp
 This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec).
 It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html).
 
-For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/PostgreSql#running-on-tanzu-application-platform-tap.
+For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/PostgreSql#running-on-tanzu-application-platform-tap.

api/v4/connectors/rabbitmq.md

@@ -82,7 +82,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `IConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/RabbitMQ.
+A complete sample app that uses `IConnection` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ.
 
 ## Cloud Foundry
 
@@ -107,4 +107,4 @@ cf restage myApp
 This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec).
 It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html).
 
-For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/RabbitMQ#running-on-tanzu-application-platform-tap.
+For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/RabbitMQ#running-on-tanzu-application-platform-tap.

api/v4/connectors/redis.md

@@ -81,7 +81,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `IConnectionMultiplexer` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/Redis.
+A complete sample app that uses `IConnectionMultiplexer` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis.
 
 ### Use IDistributedCache
 
@@ -109,7 +109,7 @@ public class HomeController : Controller
 }
 ```
 
-A complete sample app that uses `IDistributedCache` is provided at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/Redis.
+A complete sample app that uses `IDistributedCache` is provided at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis.
 
 ## Cloud Foundry
 
@@ -136,4 +136,4 @@ cf restage myApp
 This Connector supports the [Service Binding Specification for Kubernetes](https://github.com/servicebinding/spec).
 It can be used through the Bitnami [Services Toolkit](https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.5/tap/services-toolkit-install-services-toolkit.html).
 
-For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/latest/Connectors/src/Redis#running-on-tanzu-application-platform-tap.
+For details on how to use this, see the instructions at https://github.com/SteeltoeOSS/Samples/tree/main/Connectors/src/Redis#running-on-tanzu-application-platform-tap.

api/v4/fileshares/usage.md

@@ -40,7 +40,7 @@ Credentials are generally required for interacting with SMB shares. `WindowsNetw
 
 When used in conjunction with the Cloud Foundry Configuration Provider, you can access the values as follows:
 
-```
+```shell
 dotnet add package Steeltoe.Configuration.CloudFoundry
 dotnet add package Steeltoe.Common.Net
 ```

api/v4/logging/index.md

@@ -1,6 +1,6 @@
 # Dynamic Logging
 
-Steeltoe includes two logging providers that enhance existing logger libraries with support for managing minimum log levels at runtime through the [Steeltoe Management logger endpoint](../management/loggers.md) and [recording distributed trace information](../tracing/index.md#enabling-log-correlation).
+Steeltoe includes two logging providers that enhance existing logger libraries with support for managing minimum log levels at runtime through the [Steeltoe Management logger endpoint](../management/loggers.md) and [recording distributed trace information](../tracing/index.md#log-correlation).
 
 * [Dynamic Console Logging](./dynamic-console-logging.md) works with `Microsoft.Extensions.Logging.Console`.
 * [Dynamic Serilog Logging](./dynamic-serilog-logging.md) works with `Serilog`

api/v4/management/cloud-foundry.md

@@ -1,31 +1,15 @@
 # Cloud Foundry Integration
 
-Integration with Apps Manager is accomplished by adding the Cloud Foundry management endpoint to your application. When used, this endpoint enables the following additional functionality on Cloud Foundry:
+Integration with [Tanzu Apps Manager](https://techdocs.broadcom.com/us/en/vmware-tanzu/platform/tanzu-platform-for-cloud-foundry/10-0/tpcf/console-index.html) is accomplished by adding the Cloud Foundry management endpoint to your application.
 
-* Provides an alternate, secured route to the endpoints expected by Apps Manager and configured in your application.
-* Exposes an endpoint that can be queried to return the IDs of and links to the enabled management endpoints in the application.
-* Adds Cloud Foundry security middleware to the request pipeline, to secure access to the management endpoints by using security tokens acquired from the UAA.
+When used, this endpoint enables the following additional functionality on Cloud Foundry:
 
-> [!NOTE]
-> The Cloud Foundry integration will not work unless the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured.
-
-## Security
-
-When adding this management endpoint to your application, the Cloud Foundry security middleware is added to the request processing pipeline of your application to enforce that, when a request is made to any of the management endpoints, a valid UAA access token is provided as part of that request. Additionally, the security middleware uses the token to determine whether the authenticated user has permission to access the management endpoint.
+* A variant of the [hypermedia](./hypermedia.md) endpoint is registered at `/cloudfoundryapplication`.
+* All endpoints are additionally mapped under the base path `/cloudfoundryapplication`.
+* [Authentication and authorization](#security) for your Cloud Foundry environment is added to the request pipeline.
 
 > [!NOTE]
-> The Cloud Foundry security middleware is only active when your application is running on Cloud Foundry.
-
-## External access
-
-When running in Cloud Foundry, it is possible to access the endpoints via the [hypermedia](./hypermedia.md) URL, which defaults to `/actuator`. In other words, you can also access all your endpoints from this URL prefix. For example, the [info](./info.md) endpoint would be accessible at `/actuator/info`.
-
-While the endpoints provided on the `/cloudfoundryapplication` path are secured as described above, the endpoints provided on the `/actuator` path are not.
-For this reason, all endpoints are exposed by default at `/cloudfoundryapplication`, but only health and info are exposed by default at `/actuator`.
-In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints).
-
-> [!CAUTION]
-> Applying an authorization policy on `/actuator` will also impact `/cloudfoundryapplication`, which will break the integration with Apps Manager.
+> The Cloud Foundry integration will not work unless the [Cloud Foundry Configuration Provider](../configuration/cloud-foundry-provider.md) has also been configured.
 
 ## Configure Settings
 
@@ -50,7 +34,7 @@ The default path is `/cloudfoundryapplication`.
 
 See the [Exposing Endpoints](./using-endpoints.md#exposing-endpoints) and [HTTP Access](./using-endpoints.md#http-access) sections for the overall steps required to enable HTTP access to endpoints in an ASP.NET Core application.
 
-To add the actuator to the service container, add a CORS policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method.
+To add the actuator to the service container, add a [CORS](#cross-origin-resource-sharing) policy, register security middleware and map its route, use the `AddCloudFoundryActuator` extension method.
 
 Add the following code to `Program.cs` to use the actuator endpoint:
 
@@ -66,3 +50,32 @@ builder.Services.AddCloudFoundryActuator();
 > [!TIP]
 > It's recommended to use `AddAllActuators()` instead of adding individual actuators,
 > which enables individually turning them on/off at runtime via configuration.
+
+### Cross Origin Resource Sharing
+
+When viewing an application in Apps Manager, HTTP requests are sent directly to application instances with the bearer token of the logged-in user attached.
+The nature of this integration requires the use of Cross Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)).
+The policy defined in Steeltoe intends to limit sharing to the minimum required for the endpoints to function, however there is no way for Steeltoe to discover or even guess at what the origin of an Apps Manager instance could be.
+As such, the default policy will allow any origin, unless the policy is customized. You should consider [customizing the CORS policy](./using-endpoints.md#customizing-the-cors-policy) to be more specific.
+
+## Security
+
+When adding this management endpoint to your application, the Cloud Foundry security middleware is added to the request processing pipeline of your application.
+The Cloud Foundry security middleware requires a valid UAA access token to be provided as part of any request to any of the management endpoints.
+Additionally, the security middleware evaluates the token to determine whether the authenticated user has permission to access the management endpoint.
+
+> [!NOTE]
+> The Cloud Foundry security middleware is only active when your application is running on Cloud Foundry.
+
+## External access
+
+When running in Cloud Foundry, it is still possible to access the endpoints via the [hypermedia](./hypermedia.md) URL, which defaults to `/actuator`.
+In other words, you can also access all your endpoints from this URL prefix. For example, the [info](./info.md) endpoint would be accessible at `/actuator/info`.
+
+While the endpoints provided on the `/cloudfoundryapplication` path are secured as described above, the endpoints provided on the `/actuator` path are not.
+For this reason, all endpoints are exposed by default at `/cloudfoundryapplication`, but only health and info are exposed by default at `/actuator`.
+In addition, the endpoints may be secured by whatever security mechanism the application itself uses. For more details, see [securing actuators](./using-endpoints.md#securing-endpoints).
+
+> [!CAUTION]
+> Applying an authorization policy on `/actuator` will also impact `/cloudfoundryapplication`, which will break the integration with Apps Manager.
+> In order to prevent public access to `/actuator` when running on Cloud Foundry, consider configuring actuators to [use an alternate port](./using-endpoints.md#configure-global-settings).