First steps

To help you get started, we have put together a quick-start guide to show you how to use the platform.

Table of contents
  1. 1. Create your first numbering policy
  2. 2. Add a project to the numbering policy
  3. 3. Add error codes to your project’s sourcecode
  4. 4. Test & tweak the agent configuration
  5. 5. Disable sandbox mode and git commit error codes
  6. 6. Persist error codes in Err0
  7. 7. Create a software (product or service)
  8. 8. Track your latest software versions
  9. 9. Contribute with your error codes knowledge base
  10. 10. Report error hits back to Err0

1. Create your first numbering policy

A numbering policy groups projects, it is like a namespace so you can keep different products and services isolated from each other but still apply common numbering policies.

2. Add a project to the numbering policy

Projects are part of a numbering policy and they are linked with a GIT repository (just one). A software product is usually a combination of different projects, if this is your case, you will be able to do so later, by creating a software.

3. Add error codes to your project’s sourcecode

Showing instructions for: Linux

Docker needs to be installed in the system.

  1. Navigate to Projects > Your project > Agent API tokens.
  2. Create a new API token.
  3. Click on the robot icon to download the token and the scripts err0-insert.sh and err0-check.sh.
  4. Starting with a clean git checkout, use the err0-insert.sh script to add error codes to your project’s sourcecode. Do not git commit the changes yet as the project is in sandbox mode.
  5. Review the changes with a git diff to make sure that the proper logs and exceptions have been detected.
  6. You can tweak the agent’s configuration as explained on the next step if needed.
yourproject$ sh err0-insert.sh
yourproject$ git diff # to see what err0 would do
yourproject$ git checkout -f # to abandon the change and reset to git version

A little more about the scripts:

  • insert: generates and inserts error codes into your sourcecode.
  • check: checks committed error codes are complete and publishes versions via err0. On a “commit branch” (think “main” or “master”) we track the error code’s move from a development branch into a production branch. For testing, you can mark a branch as a “commit” branch where check will create ‘committed’ error codes in err0.

4. Test & tweak the agent configuration

  1. Navigate to Projects > Your project and look at the settings on the right panel.
  2. Include and exclude directories as needed. You may also want to avoid adding error codes to some of the exceptions.
  3. Then run the err0-insert.sh script again and review the changes.
  4. Repeat this process until you are satisfied with the result.

We recommend to exclude:

  • Third party dependencies that are part of the code
  • Auto-generated files, pre-build and build directories
  • Unit test files

5. Disable sandbox mode and git commit error codes

  1. Navigate to Projects > your project and look at the bottom of the right panel for a “Change to production mode” option.
  2. Switch on production mode.

When you disable sandbox mode, all error code data will be reset and the numbering will start again.

  1. Starting with a clean git checkout, use the err0-insert.sh script to add final error codes into your project’s sourcecode.
  2. git commit the changes.
yourproject$ sh err0-insert.sh
yourproject$ git diff # to see what err0 did do
yourproject$ git add .
yourproject$ git commit -m 'initial err0 pass'

6. Persist error codes in Err0

  1. Once you have committed your changes, push them to your main development branch.

If your main development branch is not master, please review the project configuration before moving on (Projects > Your project > Error numbers finalization).

  1. Create your release branch (we recommend following the Commit branch prefixes configuration of your project) and tag it.
  2. Finally, run the err0-check.sh script to freeze error codes.
yourproject$ sh err0-check.sh

The check script does not modify files. If it finds that an error code needs to be added somewhere, it fails. If so, you need to run the insert script to add the missing error codes and then run the check again.

We recommend integrating this step into your CI/CD pipelines. You can easily do this on Gitlab and Github.

7. Create a software (product or service)

Projects are part of a numbering policy and they are linked with a GIT repository (just one). A software product is usually a combination of different projects.

8. Track your latest software versions

Tracking software versions gets more tricky when bundling several projects together.

To solve this caveat, we allow you to create your versions by picking the exact git commits/tags of every project you would like to include, the dependencies of your software, pointing to exact codebase versions.

To build the bundle, you would need to move project git tags/commits from the right columns to the left one.

9. Contribute with your error codes knowledge base

As you deal with incidents and search for error codes, you can start to build an extensive knowledge base.

10. Report error hits back to Err0

Create a “Log Context” and a token, find one of our integrations (for example: logstash) and log instances of Err0 generated error codes from your logs into Err0 for analysis.

Back to top

Copyright © 2023 err0, all rights reserved.