Better define what an error "context" is

[dcrissman]

Exert from user doc:

context: A string delimited with "/" characters that define the context of execution where the error occurred, similar to a stack trace.

This definition leaves me struggling to understand what the context is intended to be. I don't know if it is the recursive use of the word "context" or the comparison to a stacktrace, but regardless, I don't think the definition clearly encapsulates the concept that the context is intended to represent.

For example, why would a context trace be preferred over a stacktrace for a server side error? Or maybe better, what can the context provide that could not be included in an Exception's message? A stracktrace does an excellent job showing where in the code something broke, why duplicate that? That said, a stacktrace does not give any indication of the conditions that caused the exception to be thrown (again, possibly outside of the Exception's message), which is where I think the context does a better job.

I think if we had a clear definition of "context" we could begin to look at the code and ask if various uses of context and/or exceptions are appropriate, or would the other be better?

[bserdar]

i agree that the definition is not adequate, and needs to be revised.

The crucial points are:

• Context is parsable by the client. Stack trace is not.
• Context includes data, stack trace does not.

Stack trace is valuable to the developers, so logging the stack trace is
useful.

Stack trace is not valuable to a client app. Error codes and error context
information is much more usable. Client can use the error code and context
information in Error object to display error information that actually
means something to the end user.

On Mon, Jan 19, 2015 at 1:43 PM, Dennis Crissman notifications@github.com
wrote:

Exert from user doc:

context: A string delimited with "/" characters that define the context of
execution where the error occurred, similar to a stack trace.

This definition leaves me struggling to understand what the context is
intended to be. I don't know if it is the recursive use of the word
"context" or the comparison to a stacktrace, but regardless, I don't think
the definition clearly encapsulates the concept that the context is
intended to represent.

For example, why would a context trace be preferred over a stacktrace for
a server side error? Or maybe better, what can the context provide that
could not be included in an Exception's message? A stracktrace does an
excellent job showing where in the code something broke, why duplicate
that? That said, a stacktrace does not give any indication of the
conditions that caused the exception to be thrown (again, possibly outside
of the Exception's message), which is where I think the context does a
better job.

I think if we had a clear definition of "context" we could begin to look
at the code and ask if various uses of context and/or exceptions are
appropriate, or would the other be better?

—
Reply to this email directly or view it on GitHub
#63.

[dcrissman]

+1 to all your points.

Does the context also add value to Server side issues? Say a failure on startup of Lightblue or a plugin (RDBMS, Mongo, etc)?

Does an Exception's message augment the context (or vis-versa) in any way, or are they two different things?

[bserdar]

We can throw Error on startup, but that would not be very useful. On
startup, exceptions make much more sense. There is no input variables to
capture in context during startup.

Backend plugins should throw Errors. Mongo CRUD and metadata do. The same
argument about capturing context applies: when Mongo back end throws an
Error, that object still contains the context
insert/user/1.0.0/.../mongo/translator/etc...

Ideally, Error should have a distinct code for every different situation.
But, we are lazy, and don't do that consistently.

On Mon, Jan 19, 2015 at 2:25 PM, Dennis Crissman notifications@github.com
wrote:

+1 to all your points.

Does the context also add value to Server side issues? Say a failure on
startup of Lightblue or a plugin (RDBMS, Mongo, etc)?

Does an Exception's message augment the context (or vis-versa) in any way,
or are they two different things?

—
Reply to this email directly or view it on GitHub
#63 (comment)
.

[dcrissman]

crud action, entity name, entity version, datasource (name or type? maybe both) all seem useful to me. As does any document path associated with the error.

To what degree do we want to reveal the innards of backend execution? For example a client wouldn't know what a 'translator' is.

[bserdar]

It is not "translator". It is "translateSort" "translateQuery", etc. These
are hardcoded strings, and meant to be more meaningful to an end client
than a stack trace. Could be changed to something more clear.

On Tue, Jan 20, 2015 at 9:11 AM, Dennis Crissman notifications@github.com
wrote:

crud action, entity name, entity version, datasource (name or type? maybe
both) all seem useful to me. As does any document path associated with the
error.

To what degree do we want to reveal the innards of backend execution? For
example a client wouldn't know what a 'translator' is.

—
Reply to this email directly or view it on GitHub
#63 (comment)
.

[dcrissman]

"translateSort" "translateQuery"

So these are sort of what like phase of the action that failed. I could see that being useful as long as we are consistent across modules.

Context is parsable by the client. Stack trace is not.
...
insert/user/1.0.0/.../mongo/translator/etc...

Would it make sense to split the context into a json object? If the goal is that this is "parsable by the client", then I would think this might be an easier format to consume, rather than splitting by / and then having to figuring out what elements were included.
For example, something like:

"context": {"action": "insert", "entity": "user", "entityVersion": "1.0.0", "datasource": "mongo", "phase": "translateSort", "jsonPath": "path/in/json/that/failed"}

[bserdar]

It might be a good idea, though what you described above requires some
changes to Error APIs to push not just the values, but their associated
labels as well. Instead of

Error.push("insert")

it'd become

Error.push("action","insert");

Or, we could support both forms somehow.

On Fri, Feb 6, 2015 at 8:35 AM, Dennis Crissman notifications@github.com
wrote:

"translateSort" "translateQuery"

So these are sort of what like phase of the action failed. I could see
that being useful as long as we are consistent across modules.

Context is parsable by the client. Stack trace is not.
...
insert/user/1.0.0/.../mongo/translator/etc...

Would it make sense to split the context into a json object? If the goal
is that this is "parsable by the client", then I would think this might be
an easier format to consume, rather than splitting by / and then having to
figuring out what elements were included.
For example, something like:

"context": {"action": "insert", "entity": "user", "entityVersion": "1.0.0", "datasource": "mongo", "phase": "translateSort", "jsonPath": "path/in/json/that/failed"}

—
Reply to this email directly or view it on GitHub
#63 (comment)
.