Skip to content

Raven Device Statistics API

This page gives an overview of the Raven Device Statistics API, describing its current status, where and how it's developed and deployed, and who is responsible for maintaining it.

Service Description

The Raven Device Statistics API provides statistics on unique visits recorded on raven.cam.ac.uk over one or more reporting periods.

The API is useful for getting metrics on devices currently used by University members for planning device support.

Devices are grouped by web browser make and operating system.

Reporting periods are the past day, past week and past 30 days.

Service Status

The Raven Device Statistics API is currently in alpha as part of the wider alpha testing for the API Gateway service.

Contact

Technical queries and support should be directed to raven-support@uis.cam.ac.uk and will be picked up by a member of the team working on the service. To ensure that you receive a response, always direct requests to raven-support@uis.cam.ac.uk rather than reaching out to team members directly.

Issues discovered in the service or new feature requests should be opened as GitLab issues in the infrastructure project (DevOps only). Non DevOps members may open issues in that project by emailing gitlab+uis-devops-raven-infrastructure-1920-issue-@developers.cam.ac.uk.

Environments

The Raven Device Statistics API is currently deployed to the following environments:

Name URL
Production https://api.apps.cam.ac.uk/ravenstats/
Staging https://api.apps.cam.ac.uk/ravenstats-test/
Development https://api.apps.cam.ac.uk/ravenstats-dev/

The production environment is advertised on the API Gateway developer portal. Other environments are not publicised.

Source code

The source code for the Raven Device Statistics API is present as a single Python script within the Raven infrastructure project (DevOps only). The script is run as a Cloud Scheduled Job each hour to update a static device report in a Cloud Storage object.

Technologies used

The Raven stats API is built on the following technologies:

  • Google Cloud Storage to provide the live "implementation" of the API backend.
  • Google Cloud Functions to run periodic reports.
  • Google Cloud Scheduler to trigger periodic reports.
  • Google Analytics to provide device detection.
  • The API Gateway to publish the API.

A lot of that technology is hidden within our standard scheduled script module.

Operational documentation

The following gives an overview of how the Raven Device Statistics API is deployed and maintained.

How and where the Raven Device Statistics API is deployed

The Raven Device Statistics API is deployed as both a backend proxied by the API Gateway and a product within the API Gateway itself.

The backend is a Google Storage object which is provisioned with terraform. The content of that object is rendered by a scheduled script.

The proxy is defined in the API Gateway configuration.

Deploying a new release

A new release can be deployed by applying the Raven infrastructure terraform.

Monitoring

The GCP scheduled script terraform module sets up a Cloud Monitoring alert which is fired if the script does not complete successfully sufficiently frequently.

Debugging

If the scheduled script is failing, use the GCP console to look at the logs of the Raven stats Cloud Function in the first instance.

Service Management and tech lead

The service owner for the Raven Device Statistics API is unknown pending discussion into service management for APIs.

The service manager for the Raven Device Statistics API is Rich Wareham.

The tech lead for the Raven Device Statistics API is Rich Wareham.

The following engineers have operational experience with the Raven Device Statistics API and are able to respond to support requests or incidents: