Skip to content

Event logging

Event log entries is something an end user will see. In order to improve user experience the messages should be written in a consistent way.

Here are the guidelines for writing good log events.

  • Use present perfect passive for the message.

Right: Environment %s has been created.

Wrong: Environment %s was created.

  • Build a proper sentence: start with a capital letter, end with a period.

Right: Environment %s has been created.

Wrong: environment %s has been created

  • Include entity names into the message string.

Right: User %s has gained role of %s in project %s.

Wrong: User has gained role in project.

  • Don't include too many details into the message string.

Right: Environment %s has been updated.

Wrong: Environment has been updated with name: %s, description: %s.

  • Use the name of an entity instead of its __str__.

Right: event_logger.info('Environment %s has been updated.', env.name)

Wrong: event_logger.info('Environment %s has been updated.', env)

  • Don't put quotes around names or entity types.

Right: Environment %s has been created.

Wrong: Environment "%s" has been created.

  • Don't capitalize entity types.

Right: User %s has gained role of %s in project %s.

Wrong: User %s has gained Role of %s in Project %s.

  • For actions that require background processing log both start of the process and its outcome.

Success flow:

  1. log Environment %s creation has been started. within HTTP request handler;

  2. log Environment %s has been created. at the end of background task.

Failure flow:

  1. log Environment %s creation has been started. within HTTP request handler;

  2. log Environment %s creation has failed. at the end of background task.

  3. For actions that can be processed within HTTP request handler log only success.

Success flow:

log User %s has been created. at the end of HTTP request handler.

Failure flow:

don't log anything, since most of the errors that could happen here are validation errors that would be corrected by user and then resubmitted.


Last update: 2021-10-06