News

Ein Log – vielseitige Vorteile

Hast du dich schon einmal gefragt, welches Team-Mitglied diesen Server namens "test" erstellt hat? Oder wann du ein bestimmtes System zum letzten Mal hart rebooten musstest? Im Audit-Log findest du die Antwort: Die Änderungen an deinen Cloud-Ressourcen – egal, ob sie im Cloud Control Panel oder via API vorgenommen wurden – sind fein säuberlich aufgeführt und nachvollziehbar.

Wer diese Logs nicht nur im Control Panel einsehen, sondern etwa auf einem eigenen Logserver aufbewahren oder mit einem bestimmten Tool durchsuchen möchte, kann das Audit-Log neu auch über unsere API abrufen. Optional kannst du dabei einen Start- und/oder Endzeitpunkt mit angeben, um umfangreiche Logs auf den relevanten Zeitraum einzugrenzen. Mit einer speziellen poll_more URL kannst du dir zudem periodisch genau jene Logs ausgeben lassen, die seit dem letzten Abruf neu hinzugekommen sind. So kannst du die Logs auch in einem Monitoring-System auswerten und etwa bei bestimmten Aktionen ein zusätzliches Augenpaar für ein manuelles Review aufbieten.

Blick unter die Haube

Im Audit-Log, das du via API abrufst, findest du nebst dem exakten Timestamp für jede Änderung die zwei Felder action und message. Die Action benennt dabei, um was für eine Änderung es sich handelt (z.B. "server_volume_attach"), während die Message den ganzen Vorgang beschreibt – also auch angibt, welches Volume an welchen Server angehängt wurde. Daneben siehst du, wer die Änderung veranlasst hat (in der Regel die Mail-Adresse eines Accounts im Control Panel bzw. das benutzte API-Token), und von welcher IP-Adresse aus dies geschah. Alle Details dazu findest du wie immer in unserer API-Dokumentation.

Nicht jede Änderung via Control Panel oder API dauert gleich lang, und Aktionen können parallel laufen. Sobald die Aktion erfolgreich durchgeführt wurde, wird der Logeintrag vorbereitet – dies bestimmt den Timestamp des Logs. Kurz darauf (im Bereich von Millisekunden) wird das Resultat der Aktion und der Logeintrag sichtbar gemacht. In dieser kurzen Zeit ist es möglich, dass Logeinträge sich "überholen", also ein Log mit dem früheren Timestamp erst später sichtbar wird. Beim Abruf von Folgeseiten und beim "Pollen" stellt der cursor sicher, dass dir kein Logeintrag entgeht. Einen umfassenden Einblick in diesen Mechanismus gibt dir Michi in unserem Engineering Blog.

Vorbereitetes Code-Beispiel: sofort loslegen

Zum schnellen Einstieg haben wir für dich ein fixfertiges, kommentiertes Python-Script vorbereitet. Damit kannst du das Abrufen des Audit-Logs via API ausprobieren und dich mit dem verwendeten Ansatz vertraut machen. Auch wenn du in deiner Praxis andere Tools und Sprachen nutzt, hast du damit einen guten Überblick und eine Basis für eigene Implementierungen.

Bereite als erstes ein Python Virtual Environment mit der benötigten Dependency vor:

mkdir project-log-api-client
cd project-log-api-client/
python3 -m venv venv
source venv/bin/activate
pip install aiohttp

Erstelle dann das eigentliche Script api-log-client.py mit folgendem Inhalt:

import asyncio
import json
from collections.abc import AsyncIterator
from datetime import UTC
from datetime import datetime
from datetime import timedelta
from typing import Any
from urllib.parse import quote

from aiohttp import ClientSession

API_TOKEN = "INSERT_PROJECT_API_TOKEN"
POLL_INTERVAL_SECONDS = 120


async def stream_logs(session: ClientSession, start: datetime) -> AsyncIterator[Any]:
    poll_url = f"https://api.cloudscale.ch/v1/project-logs?start={quote(start.isoformat())}"

    # The outer loop fetches all logs available at the time,
    # then waits for a defined interval.
    while True:
        current_page = poll_url

        # The inner loop fetches individual pages of available logs
        # until the `next` field in the response is `null`.
        while current_page is not None:
            async with session.get(current_page) as response:
                if not response.ok:
                    # The API did not return with status code 200.
                    raise Exception(f"Error {response.status} from API: {await response.text()}")

                obj = await response.json()

            # Return all fetched logs to the caller.
            for log in obj["results"]:
                yield log

            current_page = obj["next"]
            poll_url = obj["poll_more"]

        # Wait for a defined interval before polling for new logs.
        await asyncio.sleep(POLL_INTERVAL_SECONDS)


async def main() -> None:
    # Header to authenticate the API access.
    headers = {"Authorization": f"Bearer {API_TOKEN}"}

    # Retrieve logs from the past hour before streaming new logs.
    start = datetime.now(UTC).astimezone() - timedelta(hours=1)

    print(f"Streaming logs, starting from {start:%F %H:%M:%S}. Use ctrl-C to stop.")

    async with ClientSession(headers=headers) as session:
        # Iterate over logs returned by the API and print them to the console.
        async for log in stream_logs(session, start):
            print(json.dumps(log, indent=4))


if __name__ == "__main__":
    asyncio.run(main())

Starte nun das Script. Es gibt dir das Audit-Log der letzten 60 Minuten auf der Kommandozeile aus und ergänzt dann periodisch Logeinträge, die in der Zwischenzeit neu hinzugekommen sind:

$ python3 api-log-client.py 
Streaming logs, starting from 2025-12-11 12:21:48. Use ctrl-C to stop.
{
    "ip_address": "172.30.244.1",
    "action": "server_create",
    "message": "Server 'hello' has been created",
    "timestamp": "2025-12-11T12:23:17.460366Z",
    "actor": {
        "user": {
            "email": "johanna@example.com"
        }
    }
}
[...]

Mit den Audit-Logs deiner Projekte bei cloudscale weisst du jederzeit, wann, was und von wem gemacht wurde – so kannst du schnell die richtigen Zusammenhänge herstellen oder bei Nachfragen auf die geeigneten Personen zugehen. Nutze diese Logs nun auch via API für maximale Flexibilität bei Archivierung und Auswertungen.

Verbindlich,
Dein cloudscale-Team