Might be worth adding a caveat: libraries should default to creating a no-op logger if the user didn't pass one in, that makes it easier to ensure that the logger is always propagated through the library.

I intentionally didn't add this since I think this is a topic of contention right now. I personally think this is a bad pattern since I have seen many cases where the default parameter led to folks not passing in their logger and when debugging they didn't get log statements. I personally much rather prefer having a non-optional non-defaulted parameter since it requires users attention. However, I think there is design space here by leveraging structured concurrency more to avoid all these manual passings of loggers altogether.

Yeah dots is a good recommendation I think... if some specific backend needs something else they can do what prometheus does in metrics for labels (nameAndLabelSanitizer) 👍

Are those considered equivalent?

logger.debug(
    "Database operation completed",
    metadata: [
        "db.operation": "SELECT",
        "db.table": "users",
        "db.duration": "\(duration)",
        "db.rows": "\(rowCount)"
    ]
)

and

logger.debug(
    "Database operation completed",
    metadata: [
        "db": [
            "operation": "SELECT",
            "table": "users",
            "duration": "\(duration)",
            "rows": "\(rowCount)"
        ]
    ]
)

No they are not. They result in different metadata being generated.

The second one also requires another dictionary allocation

The best practices listed are OK, however it somewhat pretty weird to call out tracing as motivation and not mention the way tracing actually integrates with logging -- which isn't this pattern (regardless of opinions on status quo).

I'd just drop "distributed tracing" from the motivation entirely if the examples are not going to address it at all, causes some confusion as it's not showing off how currently tracing actually integrates with loggers today.

I dropped tracing and just kept the correlation IDs part.

Would you consider splitting this one into a separate PR to allow us to discuss more, without blocking the other changes? I have more thoughts here.