Update usage guide for v3.0.0 #245

Activity

1. daniel-sanche

   added

   api: loggingIssues related to the googleapis/python-logging API.Issues related to the googleapis/python-logging API.

   type: docsImprovement to the documentation for an API.Improvement to the documentation for an API.

   priority: p3Desirable enhancement or fix. May not be included in next release.Desirable enhancement or fix. May not be included in next release.

   on Mar 29, 2021
2. daniel-sanche

   added this to the v3.0.0 Breaking milestone on Mar 29, 2021
3. daniel-sanche

   self-assigned this

   on Mar 29, 2021
4. keenan-devrel

   added

   type: processA process-related concern. May include testing, release, or the like.A process-related concern. May include testing, release, or the like.

   and removed

   type: docsImprovement to the documentation for an API.Improvement to the documentation for an API.

   on Oct 19, 2021
5. daniel-sanche commented on Nov 29, 2021

   

   daniel-sanche

   on Nov 29, 2021

   ContributorAuthor

   More actions

   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
   
6. daniel-sanche

   closed this as completedon Jan 26, 2022