docs: improve write structured logEntry example#986
Conversation
Codecov Report
@@ Coverage Diff @@
## master #986 +/- ##
=======================================
Coverage 98.39% 98.39%
=======================================
Files 18 18
Lines 12985 12985
Branches 399 399
=======================================
Hits 12776 12776
Misses 207 207
Partials 2 2 Continue to review full report at Codecov.
|
| const json_Entry = log.entry(metadata, message); | ||
|
|
||
| // Synchronously write the log entry | ||
| await log.write(text_entry); |
There was a problem hiding this comment.
As this is written right now, the user will see await calls without a wrapping async function. This will lead to copy/paste code that doesn't work sadly. This needs an outer main function that holds an async function that does an await. I know this is kind of terrible. For a good example:
https://github.com/googleapis/nodejs-bigquery/blob/master/samples/addColumnLoadAppend.js
There was a problem hiding this comment.
Ah yes we want it to be copy&paste runnable.
@JustinBeckwith should I refactor all node tests to have an outer main (might take some time).
Or is it ok if I wrap the await call inside an async function like the current state of the example?
...
async function writeLogEntry() {
// Save the two log entries. You can write entries one at a time, but it is
// best to write multiple entires together in a batch.
await log.write([entry, secondEntry]);
console.log(`Wrote to ${logName}`);
}
writeLogEntry();
``There was a problem hiding this comment.
Shouldn't have to refactor the tests - just the samples themselves. What you have written there is perfect. That whole thing though ends up in it's own main function usually.
There was a problem hiding this comment.
👍 updated . thanks for the feedback!
|
|
||
| console.log(`Wrote to ${logName}`); | ||
| } | ||
| writeLogEntry(); |
There was a problem hiding this comment.
Is this supposed to be inside the region tag?
Edit: nvm. I realized there's an inner and outer writeLogEntry. I'd probably suggest removing inner the function to keep it simpler, but I see it was like this before you touched it
| */ | ||
| // const logName = 'Name of the log to write to, e.g. my-log'; | ||
|
|
||
| // const logName = 'my-log'; |
There was a problem hiding this comment.
If you don't want to have this as a comment, this should also work:
async function writeLogEntry(inputName) {
...
var logName = 'my-log';
[END logging_write_log_entry]
logName = inputName;
[START logging_write_log_entry]
...
The two halves of the region tag will be concatenated together, and the snippet will be both readable and testable
| favorite_color: 'Blue', | ||
| } | ||
| ); | ||
| const json_Entry = log.entry(metadata, message); |
There was a problem hiding this comment.
More comments might be useful here. I wonder if users will be confused about the multiple logging payloads
| // Asynchronously let the logging library dispatch logs | ||
| log.write(text_entry); | ||
|
|
||
| console.log(`Wrote to ${logName}`); |
There was a problem hiding this comment.
It seems a bit weird to be doing log and console.log. Is there any reason?
Fixes #973 🦕
For internal reference, here's the canonical sample