Setting up sources of evidence

Each source of evidenceevidence - Real traffic to your API. Evidence verifies certain API behaviors across specific commits, builds and environments. It provides a link between your specification and your API's behavior in reality. is defined by its contextwhere is the evidence coming from?

The context, combined with real traffic, allows Optic to compute evidence and update its understanding of how your API is behaving across all its environments.

  • Is it test traffic?
    • For what PR / commit? i.e. pr-153 sha 85cbaad.
  • Is this running in a real environment?
    • What does your team call that environment? i.e. Staging.
    • What build is running here? i.e. build-763.

Gathering evidence from CI

In this example, our API tests run in each PR. We spin up the Optic Capture Toolkit in the background to monitor traffic on port 3000. We pass in the PR and SHA from GitHub as the context.

As our tests run, Optic will compute the evidence on the fly and stream that up to Optic's Evidence API. Our tests run, exit, and cleanup as they normally would, but now that test traffic is also used as Evidence in Optic!

- name: Configure Optic Evidence
  run: optic sniff 3000 --ci-evidence --pr $GITHUB_PR --sha $GITHUB_SHA
      OPTIC_API_KEY: ${{secrets.OPTIC_API_KEY}}
- name: Run API tests
    run: npm run tests --port 3000

Ready to get set up? Explore all the supported evidence sources here

Gathering evidence from Real Environments

The quickest way to gather evidence from a real environment is to add an Evidence Agent to your Dockerfile. This will start Optic in the background and stream evidence (not actual traffic) up to Optic's Evidence API.

The Evidence Agent is open source, built in Rust, blazing fast, and uses very little memory.

FROM ...
# your setup
RUN apt get-install ...optic
# update start command
CMD optic sniff 3000 --evidence --env $ENV_NAME --build $BUILD_ID &

For a more scalable solution, use our Kubernetes or Docker Compose setup to configure the Agent as another container or sidecar.

Ready to get set up? Explore all the supported evidence sources here.

API Gateways and Service Meshes


Enterprise Teams:

Optic's customer success team can help you assess the best places to collect traffic in your stack that are performant, and makes sure no new points of failure are introduced.

Did this page help you?