Update usage guide for v3.0.0

[daniel-sanche]

As part of the v3.0.0 release, we should update the usage guide. It should mention newer GCP platforms, and talk about new features

• explain deprecated classes, and give a clear path forward (link)
• document get_default_handler (link)

[daniel-sanche]

Here's one comment from a customer that should be considered when updating the user guide:

A customer tries to correlate request and container logs as per [1] using python Cloud Logging client library.

First, the documentation [1] states:

Container logs are not automatically correlated to request logs unless you use a Cloud Logging client library.

That made him (and me) believe that Cloud Logging client library would add all needed fields to the application logs automatically, so they are correlated in the Logs Explorer. Eventually, we found out that it's not true and everything has to be done manually. Moreover, we don't have the list of needed fields for that, and samples are very simple [2] and don't cover this scenario.

By trials and errors and using some unit tests code [3] I determined that the mandatory fields are:

trace
resource.type
resource.labels And trace and resource.type fields in the child log entry (application) must be the same as in the parent log entry (http requests)
Some external resources [4] also mention the same:

The values for resource.type, resource.labels, and trace must be the same in the parent and its child(ren).

And it's not the first time when users complain about insufficient documentation [5]

So I see several issues here

[1] says that logs automatically correlated when Cloud Logging client library is used. It's not true, at least for Python library
Usage examples [2] are very basic and don't caver more advanced scenarios
It's not clear what fields have to be added/populated to correlate logs
Could we do anything regarding this? Some documentation updates/improves?

[1] https://cloud.google.com/run/docs/logging#correlate-logs
[2] https://googleapis.dev/python/logging/latest/usage.html#writing-log-entries
[3] https://github.com/googleapis/python-logging/blob/db9da3700511b5a24c3c44c9f4377705937caf46/tests/unit/test_logger.py#L305
[4] https://medium.com/google-cloud/combining-correlated-log-lines-in-google-stackdriver-dd23284aeb29
[5] https://github.com/googleapis/google-cloud-python/issues/7457