lasuite-drive/docs/metrics.md

Metrics API Route

Drive provides a route to export metrics to external tools. At the moment, only the storage_used metric is exposed.

The route is:

GET /external_api/v1.0/metrics/usage/

You must provide an authorization header as follows:

Authorization: Api-Key <key>

You should also provide account_type=user|organization query parameter.

Enabling

By default, this route is not available. You need to set the setting METRICS_ENABLED to True.

How to get the API key

You need to log into the Django admin and then go to Api keys.

Click Add Api Key.

You can then provide a name and submit.

An alert will then be shown at the top of the screen: "The API key for test is: ." Please store it somewhere safe: you will not be able to see it again."

🚨 IT IS THE ONLY TIME THE KEY IS SHOWN, COPY IT ELSEWHERE IN A SAFE PLACE 🚨

Response

The response will look like this:

{
    "count": 123,
    "next": None,
    "previous": None,
    "results": [
        {
            "account": {
                "type": "user",
                "id": "<uuid>",
                "email": "john.doe@example.com",
            },
            "metrics": {
                "storage_used": 100,
            },
        },
        {
            "account": {
                "type": "user",
                "id": <uuid>,
                "email": "johnette.doe@example.com",
            },
            "metrics": {
                "storage_used": 0,
            },
        },
        ...
    ],
}

Each entry corresponds to a user. The response format is designed to match this spec: https://docs.numerique.gouv.fr/docs/14c29262-e9ce-486a-9ced-3c766bd8abf7/

The storage_used is, by default, the sum of file sizes created by the user, in bytes.

Filtering

You can filter this by using account_id_key and account_id_value query parameter like so:

• account_type | user or organization
• account_id_key | The key to filter on (sub or email for account_type=user). Required if account_type=organization, it could be any oidc stored claim.
• account_id_value | The value to filter on. Required if account_type=organization.
• account_email | This will soon be migrated to _key _value pattern, but still needed.

Examples:

GET /external_api/v1.0/metrics/usage/?account_type=user
GET /external_api/v1.0/metrics/usage/?account_type=user&account_id_key=sub&account_id_value=<sub value>
GET /external_api/v1.0/metrics/usage/?account_type=user&account_email=<email>
GET /external_api/v1.0/metrics/usage/?account_type=organization # Forbidden
GET /external_api/v1.0/metrics/usage/?account_type=organization&account_id_key=siret&account_id_value=<siret value>

How to customize the storage used computation?

The way the storage_used metric is computed may not match the way you want it to work. To customize it, you will need to customize the STORAGE_COMPUTE_BACKEND setting and provide a custom implementation that extends StorageComputeBackend.

You can see the default implementation CreatorStorageComputeBackend as an example.

Expose OIDC claims

For aggregation purposes, you might want to expose some OIDC claims from this route that your external tool will use.

For instance, with the deploy center, the implementation needs to get access to the siret claim.

Simply customize the setting METRICS_USER_CLAIMS_EXPOSED=your_claim1,your_claim2 and the response will look like this:

{
    "count": 123,
    "next": None,
    "previous": None,
    "results": [
        {
            "account": {
                "type": "user",
                "id": "<uuid>",
                "email": "john.doe@example.com",
            },
            "your_claim1": <value>,
            "your_claim2": <value>,
            "metrics": {
                "storage_used": 100,
            },
        },
        ...
    ],
}

🚨 Make sure the claims you want to expose are stored by using the OIDC_STORE_CLAIMS setting as well. Otherwise, it will not work. 🚨

Organization metrics

It is possibe to fetch usage metric grouped by organization, do to so, provide account_type=organization, when using account_type organization it is required that you also provide account_id_key=siret and account_id_value=1234....

It will sum the storage_used by user that have the same "claims.siret".

You should mind to add siret into OIDC_STORE_CLAIMS so the siret are stored on user records.

Example:

GET /external_api/v1.0/metrics/usage?account_type=organization&account_id_key=siret&account_id_value=12345678900001
{
    "count": 123,
    "next": None,
    "previous": None,
    "results": [
        {
            "account": {
                "type": "organization",
            },
            "siret": "12345678900001"
            "metrics": {
                "storage_used": 10000000,
            },
        },
        ...
    ],
}