README.md

Advanced Example

This example demonstrates using the optional features and customizations Pyctuator is offering.

Running the example

Before running this example, you'll need SBA (Spring Boot Admin), MySQL and Redis running on the same machine the example application will be running.

It is recommended to start these services using the docker-compose.yml part of this example, from the examples/Advanced directory perform:

docker-compose --project-name example --file docker-compose.yml up --detach --force-recreate

Next, from the examples/Advanced directory, run the example application using poetry as follows:

poetry install
poetry run python advanced_example_app.py

Using the example

The example application, available from http://localhost:8000 exposes example APIs for accessing the DB and Redis:

• http://localhost/db/version - returns the DB's version
• http://localhost:8000/redis/a-key - returns the value of the a-key key in redis

Connect to Spring Boot Admin using http://localhost:8082.

Insights Details

1. Monitor disk space (requires psutil):
2. Monitor connection to the DB (requies sqlalchemy and drivers specific to the DB being used)
3. Monitor Redis client (requires redis)
4. Show build details
5. Show Git details

Insights Metrics

If psutil is installed, Pyctuator provides various process metrics in the "Metrics" tab:

Insights Environment

Pyctuator automatically exposes all environment variables, after scrubbing secrets, via the "Environment" tab under "systemEnvironment":

Additionally, Pyctuator can be configured to expose application-specific configuration via SBA (after scrubbing commonly identified secrets): Note that SBA only support flattened configuration hierarchy, which is automatically handled by Pyctuator.

Secret scrubbing

Pyctuator is using a "secret scrubber" for scrubbing/masking secrets from environment-variables and config-entries that are being reported to SBA. The default secret scrubber is taking care fore masking values of keys that are expected to keep secrets. Additionally, the default scrubber is masking credentials that are included in URLs.

It is possible to override the default scrubber by calling set_secret_scrubber providing it a mapping function that will hide/mask the desired keys. Note that the pattern used by the built in SecretScrubber can be replaced.

For example:

pyctuator = Pyctuator(...)  # arguments removed for brevity
secret_scrubber = SecretScrubber(keys_to_scrub=re.compile("^ABC$|^xyz$", re.IGNORECASE)).scrub_secrets
pyctuator.set_secret_scrubber(secret_scrubber)

Further customization

Using Pyctuator, it is possible to have SBA monitor application-specific health aspects using custom health-providers.

Health status may include multiple checks and may also include details on failures or the apps health.

To demonstrate this, the example application exposes additional API for setting the health, http://localhost:8000/health - posting a JSON formatted pyctuator.health_provider.HealthDetails to set the current health status.

For example, the call bellow will make the application report its down.

curl -X POST localhost:8000/health -d '{"status": "DOWN", "details": {"backend_connectivity": "Down", "available_resources": 41}}'