improve log API

[pq]

Follow-up from #16 (comment), minimally we should add:

• a toEncodable callback (if we want to rely on json encodeability for data objects, we should have an optional convert param for LogMessageCallback #10)
• logError and
• support for data objects

@devoncarew: would 2 calls be sufficient?:

void log(MessageCallback messageCallback, {Object data, toEncodable(object)});

void logError(MessageCallback messageCallback, {Object error, toEncodable(object), StackTrace stackTrace});

Or do you think there's benefit in making a distinction between log and logData?

[devoncarew]

W/ logData, we could tell the API user that there were some conventions about how to transmit the data; that we'd expect it to be jsonable, and would send over the object encoded as a json string.

Putting the data object as a json encoded string in the error: field is pretty prescriptive however. Perhaps have log() - that can take an optional data: param - and have a separate logDataAsJson(), which does the prescriptive encoding?

void log(MessageCallback messageCallback, {Object data, toEncodable(object)});

looks good!

void logError(MessageCallback messageCallback, {Object error, toEncodable(object), StackTrace stackTrace});

perhaps drop the toEncodable here? I think in this case we would not try and encode the object, but would just pass the reference as is into the dart:developer call.

[pq]

What do we know about constraints on the error object in the developer:log API? I was working on the assumption that the error object would ultimately be encoded as json but realize now that may not be right!

[devoncarew]

It's just sent as a VM protocol reference - you can then call service protocol methods to get more info about it. From the client, you basically just see the vm service protocol id for the object (foo/123).

[pq]

#20 adds data logging but we'll want to keep iterating.

food for thought from @devoncarew on that PR:

• a dedicated logData call could be useful, esp. to indicate that we have a prescriptive way to write the data
• if we're very perceptive of what kind of data we can log (Map<String, Object>?), I wonder if we need both LogDataCallback data and ToJsonEncodable toJsonEncodablecallbacks? The LogDataCallback could just return a Map, and we'd document that all the objects in it needed to be jsonable (or, string, maps, lists, and ints)?

👍

[pq]

We should hammer out what we minimally need for 1.0.

#38 adds params to allow for passing of level and stackTrace down to the developer calls.

What else (if anything) do we need for v1?

/cc @devoncarew