itamarst/eliot

Eliot: the logging system that tells you *why* it happened

Eliot: Logging that tells you why it happened

Python's built-in logging and other similar systems output a stream of factoids: they're interesting, but you can't really tell what's going on.

• Why is your application slow?
• What caused this code path to be chosen?
• Why did this error happen?

Standard logging can't answer these questions.

But with a better model you could understand what and why things happened in your application. You could pinpoint performance bottlenecks, you could understand what happened when, who called what.

That is what Eliot does. eliot is a Python logging system that outputs causal chains of actions: actions can spawn other actions, and eventually they either succeed or fail. The resulting logs tell you the story of what your software did: what happened, and what caused it.

Eliot supports a range of use cases and 3rd party libraries:

• Logging within a single process.
• Causal tracing across a distributed system.
• Scientific computing, with built-in support for NumPy and Dask.
• Asyncio and Trio coroutines and the Twisted networking framework.

Eliot is only used to generate your logs; you will might need tools like Logstash and ElasticSearch to aggregate and store logs if you are using multiple processes across multiple machines.

Eliot supports Python 3.8-3.12, as well as PyPy3. It is maintained by Itamar Turner-Trauring, and released under the Apache 2.0 License.

• Read the documentation.
• Download from PyPI or conda-forge.
• Need help or have any questions? File an issue on GitHub.
• Commercial support is available from Python⇒Speed.

Testimonials

"Eliot has made tracking down causes of failure (in complex external integrations and internal uses) tremendously easier. Our errors are logged to Sentry with the Eliot task UUID. That means we can go from a Sentry notification to a high-level trace of operations—with important metadata at each operation—in a few seconds. We immediately know which user did what in which part of the system."

—Jonathan Jacobs

eliot's Issues

Python 3.3+ support

Eliot should run on modern versions of Python 3.

Show extended example of adding Eliot logging to semi-realistic code

This would be opportunity to talk about branch coverage, difference between actions and persistent objects that should be done via consistent field serialization, etc..

Document that Eliot does no disk I/O in logging thread (except that Destinations do so actually this is a little silly)

Make Eliot example code in documentation actually runnable, and automate running it

This will ensure the documentation is correct.

Probably just move code out into examples/ folder, and then add it to set of tests run by trial.

Switch to tox setup that also does sphinx, pyflakes, pyflakes3

Add helper for nested actions in Eliot

(Originally from Jean-Paul Calderone).

Here's a pattern I just stumbled back in to:

def receive(self, input):
    """                                                                                                                                       
    Add logging of state transitions to the wrapped state machine.                                                                            

    @see: L{IFiniteStateMachine.receive}                                                                                                      
    """
    def _():
        action = LOG_FSM_TRANSITION(
            self.logger,
            fsm_state=unicode(self.state), fsm_input=unicode(input))
        with action as theAction:
            output = super(_FiniteStateLogger, self).receive(input)
            theAction.addSuccessFields(
                fsm_next_state=unicode(self.state), fsm_output=unicode(output))
        return output
    return self._action.run(_)

(reminds me of Axiom programming).

It would be nice to be able to avoid the nested function when achieving this.

There could be a decorator that runs a whole function in the context of some action (eg @partOfAction(attributeNamingAction) or a context manager with self.actionAttribute.resume():

Get rid of zope.interface requirement

zope.interface really doesn't add anything, and we're only optionally supporting Twisted.

Automated tests for examples in Eliot documentation

Figure out if replacing dictionaries with class-per-message-type speeds up PyPy

PyPy runs Eliot serialization rather slower than one would expect, possibly due to dictionary copying instead of using a class per MessageType/ActionType structured message.

Error message in assertHasMessage is uninformative

twisted.trial.unittest.FailTest: No messages of type <eliot._validation.MessageType object at 0x2bb2990> isn't actually useful. Should be using the message_type/action_type value instead of class... or maybe define repr on MessageType and ActionType.

validateLogging decorator doesn't stack

Only one of the assertion functions gets passed the correct logger, I think.

Copy over relevant issues from internal HybridCluster issue tracker

Move action/timestamp field generation from Message into Logger

Generating extra fields (timestamp, action identity) is currently done in Message. These means the testing code needs to parse this, which is complex. If we moved this into Logger the testing code could be simplified.

README improvements

• Make clear that Twisted support is available but optional
• Better explanation of what it does.
• Note additional features.

Get incident identifier from current Eliot logging context

(Originally from Jean-Paul Calderone).

When a user triggers something interesting getting logged, we may want to be able to find that interesting thing easily later. One approach is to given the user a token that they can give back to us to find the relevent log area. Call this an "incident identifier".

It's possible to construct one of these for an eliot action but only by using private attributes.

Add standard out destination for logging output

For simple examples/scripts it would be useful to have a built-in "log to stdout" destination.

Make unit testing validate *all* log messages

Right now it only validates some messages, those whose Logger gets overridden.

So, change testing infrastructure to work via adding a destination, rather than monkeypatching a MemoryLogger.

Move Twisted documentation into its own section

Add documentation/config for hooking up Eliot to Logstash

HybridCluster has internal documentation and setup for using Eliot output with Logstash. Add/document this.

Simplified version of field definitions for MessageType and ActionType

Defining a MessageType/ActionType is quite verbose, and therefore discourages casual users. On the other hand, all messages should really have types.

We should provide simpler (or even completely automated) typing somehow.

Rename Action to ActionContext

This is a better explanation of what it is.

Add explicit way to finish an Action

This allows code that wants to catch exceptions itself, for example, to end an action without having to do wierd stuff.

The context manager in Action should check on exit whether action is already finished, and only do so itself if it's not already finished.

LoggedMessage.ofType doesn't work with LoggedAction.children

(Originally by Tom Prince).

I naively tried to do

action = LoggedAction.ofType(....)
message = LoggedMessage.ofType(action.children, SOME_MESSAGE)[0]

which blows up. This seems like a reasonable thing to want to do, and there doesn't seem to be a way of doing this. (Although perhaps not with exactly the code I wrote).

test_serializationErrorTraceback in test_output is sensitive to dictionary hash order

The test fails intermittently.

https://travis-ci.org/hybridcluster/eliot/jobs/24544587

`setup.py test` should do what it says

Presumably run tox.

Bug in formatting in usage doc of some of the code examples

Don't force tai64n in message output

tai64n is nice and fast, but maybe not be to the liking of all users. We shouldn't require it, just like we shouldn't require JSON.

In particular, just include seconds since epoch (see comments) since that is the information, and the destinations can encode as they wish. Also will need to change eliot.filter to not assume anything special about timestamp field, since it's not guaranteed to be in any particular format anymore.

Investigate udplog output

https://github.com/ralphm/udplog

Python 3.4 support

Mostly just adding to README and tox setup and making sure everything works.

Document installation of Eliot

pip install eliot basically, but ought to be said explicitly.

Eliot: Conversion of failed Action exception to serializable types should be done in the appropriate Fields

Right now the "reason" and "exception" fields in the failure message of an Action are converted to unicode immediately. This impedes unit testing. Better to rely on conversion in the relevant Field, as was done for tracebacks.

Move Deferred support in Action into separate class

This will probably making it easier to discover (and implement) better abstractions.

PEP 8 compatibility in the API

Most Python developers use PEP 8, we should provide method aliases that match their expectations.

Allow adding destinations per logger, in additional to global destination

The proposed new logging system for Twisted does this (https://github.com/twisted/twisted/blob/log-booyah-6750-4/docs/core/howto/logger.rst).

Immediate benefits are for unit testing:

1. It would allow implementing #47 more easily.
2. It would allow developers to decide whether to capture all log messages or just some (per-logger).

Default values for Eliot types

If we supported default values for Fields in eliot, one could omit fields that were just going to get default values.

We might also be able to get rid of Field.forTypes, replacing it with Field.forTypes, since optional None value seems to be the main use case.

Utility of some sort to view the tree structure of Eliot log messages

Web UI? command-line tool? In any case useful to understand what's going on.

`Destinations` should not catch exceptions silently

Better to let broken destinations be broken visibly.

Include epydoc API docs in Sphinx output

`with startTask()` doesn't make clear that the action ends when you leave context block

The version with explicit types is perhaps clearer, but still could be more explicit about what's going on.

Destinations should probably take dictionaries and do JSON serialization themselves

Right now the Logger does JSON serialization. This is a problem if the downstream user of the messages wants to do it itself (e.g. udplog) or if it wants to do some filtering before passing them on. Logger should just pass on the dictionary.

Rename task_uuid to task_id

UUIDness is a property that should be documented, the actual functionality is just id.

Allow task children to span threads as well as processes

We need a way to serialize task_uuid and task_level child, and then deserialize into Action again.

Get rid of extra fields in Action failure case

Failures can happen for a wide variety of reasons in different places in the code; it's unreasonable to expect a consistent set of result fields. Users can always report more data with extra messages.

API for validating dict fields

Currently there is explicit support for having fields whose values are dicts. But that only validates that the field is a dict. It doesn't make any assertion about the contents of that dict.

There are libraries for this so maybe just link in docs.

Release 0.4.0

1. Update version number.
2. Change README to remove warning.
3. Upload to PyPI.
4. Update Read The Docs.

Document Twisted log file writer

Eliot can write out logs in a way that useful for Twisted. This should be documented.

Abstraction for inspecting (and possibly creating) Eliot task levels

Eliot has a concept of task levels, e.g. "1/2/1/". Right now they are created, and in eliot.testing parsed, as strings. It might be nice to have an abstraction for dealing with them (the parsing code is ugly) and perhaps for generating them as well. The latter may have a performance impact, though.

Let a single Message Field be serialized into multiple fields

(Originally requested by Jean-Paul Calderone).

For example, I want to log a BucketWeight instance. This knows the name of the bucket to which it pertains as well as some other information. I want to write:

LOG_WEIGHT_UPDATE(weight=self)

But I can't write a serializer that will add a "bucket" key to the top-level serialized json blob. To accomplish that I have to write:

LOG_WEIGHT_UPDATE(bucket=self.bucket, weight=self)

I want a bucket top-level key because that's a very common way to filter log events. I want the serializer to do it because it's a pain to have to manually break out one of the fields.

Turn eliot.filter into a binary, and document its existence

Better documentation of task/action/message relationship

Intro makes this somewhat better, but still might be worth pulling out explicitly (glossary?) and explaining task_level etc. more clearly.