Log endpoint details at application startup to aid with issue diagnosis

[DamianEdwards]

To aid in situations where one is trying to diagnose issues related to routing, minimal API endpoints, parameter binding sources, etc. it would be beneficial for a log to be emitted containing the endpoint details as they're registered, i.e. one log per endpoint. When the endpoint is a minimal API, it should include details of how the parameters will be bound, and return type details, along with any endpoint metadata associated with the endpoint. It might be interesting to think about how other endpoint-providing sub-systems, e.g. MVC, could augment this log with relevant information too.

The log would target the DEBUG log level and include a message and a single value containing a JSON payload of the details, e.g.:

Message: Endpoint added at route "/say/{greeting}/{name}/{age?:int}

{
    "route": {
        "pattern": "/say/{greeting}/{name}/{age?:int}",
        "verbs": "GET",
        "name": null,
        "parameters": [
            {
                "name": "greeting",
                "required": true
            },
            {
                "name": "name",
                "required": true
            },
            {
                "name": "age",
                "required": false
            }
        ]
    },
    "description": {
        "name": "GetGreeting", // Would be null if we determine it was an anonymous delegate (i.e. compiler generated name)
        "delegateReturnType": "Task<string>",
        "responseProcessing": "string", // Possible values: string, JSON, IResult
        "parameters": [
            {
                "name": "greeting",
                "required": true,
                "type": "string",
                "bindingSource": "RouteData" // Possible values: RouteData, QueryString, ServiceProvider, RequestBody
            },
            {
                "name": "name",
                "required": true,
                "type": "string",
                "bindingSource": "RouteData"
            },
            {
                "name": "age",
                "required": false,
                "type": "int",
                "bindingSource": "RouteData"
            },
            {
                "name": "filter",
                "required": false,
                "type": "string",
                "bindingSource": "QueryString"
            },
            {
                "name": "db",
                "required": true,
                "type": "MyApplication.TodoDb",
                "bindingSource": "ServiceProvider"
            }
        ]
    },
    "metadata": {
        // Keys are type name, value are result of ToString()
        "EndpointNameAttribute": "GetGreeting",
        "HttpMethodMetadata": "GET",
        "MethodInfo": ""
    }
}

@davidfowl

[davidfowl]

Couple of notes:

• I don't like the name "minimalAction", it should be something else more generic "action", "description" etc.
• Do we need signature? We have the return type and arguments.
• We don't have this route information in the same place that has the binding information but we might be able to fix this with some refactoring.
• Constrains are interesting, do you think its useful to show them and why?

[DamianEdwards]

• The "minimalAction" name was meant to convey that the detail following is about the specific kind of endpoint added. In the future other endpoints might have a "controllerAction" section instead or similar. That said, I don't like the name either but it's what we've used in the relevant type names. We could just go with "description" like your suggestion says if we want something generic and don't intend to have the properties under it be consistent per node name, so in the future if we have controller actions emit this too it would also have "description" but have different properties.
• The signature is just friendly I guess and makes it easy to quickly match the log to the API delegate
• I'll trust you that we can refactor things to make emitting this possible/straightforward
• IIRC route constraints affect matching which is usually one of the hardest parts of diagnosing route issues, so I figured including the details explicitly would be useful here. Also if a custom route constraint is used this would be the place that confirms the short identifier is correctly mapped to the implementing type.

[davidfowl]

The signature is just friendly I guess and makes it easy to quickly match the log to the API delegate

I would get rid of this.

IIRC route constraints affect matching which is usually one of the hardest parts of diagnosing route issues, so I figured including the details explicitly would be useful here. Also if a custom route constraint is used this would be the place that confirms the short identifier is correctly mapped to the implementing type.

I would get rid of this as well, we'd need to flow this information and we don't have it all in the same place right now.

[DamianEdwards]

Will update the example based on the feedback

[Kahbazi]

"metadata": {
    // Keys are type name, value are result of ToString()
    "EndpointNameAttribute": "GetGreeting",

Does this mean all current implementations of metadata should override ToString() to return something meaningful?

[DamianEdwards]

@Kahbazi that would be ideal.

[Kahbazi]

@Kahbazi that would be ideal.

I'll send a PR overriding ToString() method for all metadata.

[davidfowl]

Given that we're making improvements here with throwing errors for the most common cases at startup, I think this can be punted to .NET 7.

[ghost]

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.