Merge pull request #269 from jnywong/cost-monitoring-users

Add how to guide for cloud costs per user dashboard

Author: jnywong

admin/howto/monitoring/cost-attribution.md

@@ -0,0 +1,76 @@
+# General cloud costs
+
+:::{note}
+Available for dedicated AWS clusters only (and excluding CloudBank managed accounts). Other deployments on GCP will be supported in the future.
+:::
+
+## Accessing the general cloud costs dashboard
+
+Community Champions can view the cloud cost dashboards from their Grafana instance (please see [Grafana Dashboards](grafana-dashboards.md) for how to gain access).
+
+From the main menu of Grafana, navigate to *Dashboards > Cloud cost dashboards > General cloud costs* to view the dashboard.
+
+## Understanding the cloud cost dashboard
+
+The dashboard is made of several panels:
+
+- Daily costs
+- Daily costs per hub
+- Total daily costs per component
+- Daily costs per component per hub.
+
+### Daily costs
+
+:::{figure} images/cost-attribution-daily.png
+:alt: A line graph showing daily cloud costs over a 1 month period.
+:::
+
+*Cost account* refers to the associated AWS account's *total* costs, and *Cost attributable* refers to the costs that have been *attributed* to 2i2c managed cloud infrastructure.
+
+There are some costs associated with 2i2c managed cloud infrastructure that can't be attributed. For example, the act of loading the Cloud Cost dashboard itself incurs a cost that isn't attributed to 2i2c managed cloud infrastructure but forms a small part of the total cost.
+
+If *Cost account* is significantly larger than *Cost attributable*, then in principle this should be because of activity unrelated to 2i2c managed cloud infrastructure. Please contact [support](/support.md) if you have any questions about understanding your cloud costs.
+
+:::{note}
+
+- All costs are [unblended costs](https://aws.amazon.com/blogs/aws-cloud-financial-management/understanding-your-aws-cost-datasets-a-cheat-sheet/)
+- All costs are pure usage costs, and doesn't account for credits etc.
+:::
+
+### Daily costs per hub
+
+:::{figure} images/cost-attribution-daily-per-hub.png
+:alt: A line graph showing daily cloud costs per hub over a 1 month period.
+:::
+
+Costs can sometimes be attributed to a specific hub, and that can then be seen here. A typical 2i2c-managed deployment comprises of a staging hub and a production hub, although some other communities may have extra hubs such as a workshop hub.
+
+*Cost support* reflects all 2i2c cloud infrastructure support costs that aren't attributable to a specific hub.
+
+### Total daily costs per component
+
+:::{figure} images/cost-attribution-component.png
+:alt: A time series showing daily cloud costs per component over a 1 month period.
+:::
+
+Components are groupings of cloud-provided services, such as
+
+- compute
+- home storage
+- object storage
+- networking
+- support
+
+For specific definitions, see [https://github.com/2i2c-org/jupyterhub-cost-monitoring/blob/2a810989bb1c1685277d2574d3b76e673bc6e5ad/src/jupyterhub_cost_monitoring/const_cost_aws.py#L11](https://github.com/2i2c-org/jupyterhub-cost-monitoring/blob/2a810989bb1c1685277d2574d3b76e673bc6e5ad/src/jupyterhub_cost_monitoring/const_cost_aws.py#L11).
+
+### Daily costs per component per hub
+
+:::{figure} images/cost-attribution-component-per-hub.png
+:alt: A time series showing daily cloud costs per component per hub over a 1 month period.
+:::
+
+This panel shows the same information as above, but broken down for each specific hub also.
+
+## Sharing and reporting Grafana dashboards
+
+See [Sharing and reporting Grafana dashboards](reporting.md) for how to share and generate reports from Grafana dashboards.

admin/howto/monitoring/cost-general.md

@@ -0,0 +1,40 @@
+# User cloud costs
+
+![Grafana dashboard with multiple panels showing stacked bar charts of user cloud costs over time.](https://raw.githubusercontent.com/2i2c-org/jupyterhub-cost-monitoring/refs/heads/main/images/dashboard.png)
+
+:::{note}
+Available for dedicated AWS clusters only (and excluding CloudBank managed accounts). Other deployments on GCP will be supported in the future.
+:::
+
+## Navigate to the user cloud costs dashboard
+
+From the Grafana homepage, navigate to *Home > Dashboards > Cloud cost dashboards* and then click on *User cloud costs*.
+
+This will load the dashboard, which may take a few moments to populate with data.
+
+## Understand the dashboard layout
+
+The dashboard is organized into several panels, each providing insights into different aspects of user cloud costs:
+
+- **Total by Hub**: a breakdown of total costs by hub, allowing you to see which hubs are incurring the most expenses.
+- **Total by Component**: a breakdown of total costs by component (such as compute, home storage, etc.), helping you identify which resources are driving costs.
+- **Top 5 Users**: a quick at a glance view of the top 5 users by total cost over the selected time range across all hubs and components.
+- **Hub**: individual panels for each hub, showing daily costs by users within that hub. User costs summed over all hubs and components are shown by default. Try toggling the variable `hub` at the top of the dashboard to see splits by individual hubs or the variable `component` at the top of the dashboard to filter by specific components.
+
+## Interact with the dashboard
+
+You can interact with the dashboard in several ways:
+
+- **Time Range**: use the time range selector in the top right corner to adjust the period for which data is displayed. The last 30 days are shown by default. The timezone is always UTC, since daily cost data prepared by cloud providers is typically settled at 00:00 UTC.
+- **Variables**: use the dropdowns at the top of the dashboard to filter data by hub or component.
+- **Number of users**: enter a number in the field to display the top N users by total cost over the selected time range.
+- **Legend**: click on user names in the legend to isolate or hide specific users in the graphs. You can select multiple users by holding down the `Shift` key while clicking, and double-click to reset the selection.
+- **Tooltips**: hover over data points in the graphs to see detailed information, including exact cost values and timestamps of each user.
+
+:::{tip}
+Some interactions may re-trigger additional queries to fetch data, so there may be a slight delay while the graph is updated. The latest day may not have complete data, as cloud providers often take some time to finalize daily cost data.
+:::
+
+## Sharing and reporting Grafana dashboards
+
+See [Sharing and reporting Grafana dashboards](./reporting.md) for how to share and generate reports from Grafana dashboards.

admin/howto/monitoring/cost-users.md

@@ -1,23 +1,23 @@
 # Grafana dashboards
 
 :::{note}
-Grafana dashboards are only available to communities on **dedicated** clusters. If a community is on a shared cluster and would like to discuss transitioning, please contact [[email protected]](mailto:[email protected]).
+Grafana dashboards are only available to communities on **dedicated** AWS clusters (and excludes CloudBank-managed accounts). If a community is on a shared cluster and would like to discuss transitioning, please contact [[email protected]](mailto:[email protected]).
 :::
 
-To discover the URL to the Grafana dashboard, use the [List of Running Hubs](https://infrastructure.2i2c.org/reference/hubs/) table. This table also shows which cluster each hub is running on.
+To find the URL to the Grafana dashboard for your community, use the [List of Running Hubs](https://infrastructure.2i2c.org/reference/hubs/) table.
 
-Note that data is retained for up to 3 years on 2i2c hubs.
+Note that monitoring data is retained for up to 3 years on 2i2c hubs.
 
 ## Getting a Grafana account
 
-During the hub deployment process, 2i2c engineering will send the Hub Champions an email with an invitation link to Grafana to allow them to create an account. **This invite link only lasts for seven days;** and is unique to the recipient's email address. If a new invite link is required please contact [support](support:email) to request a new invite link.
+During the hub deployment process, 2i2c engineering will send Hub Champions an email with an invitation link to Grafana to create an account. **This invite link expires after seven days;** and is unique to the recipient's email address. If a new invite link is required please contact [support](support:email).
 
 :::{figure} images/grafana-invite.png
 :alt: Screenshot of a form containing fields for email, name, username and password.
-The Grafana website after clicking invitation link.
+The Grafana website after clicking the invite link.
 :::
 
-This Grafana account is separate from the account used to log into JupyterHub. This new account has administrative privileges and will allow Hub Champions to invite others to have access to Grafana as admins or viewers for the community. See the [instructions](https://infrastructure.2i2c.org/sre-guide/support/grafana-account) for how to invite others to join Grafana.
+This Grafana account is *separate* from the account used to log into JupyterHub. This new account has administrative privileges and will allow Hub Champions to invite others to access Grafana with admin or viewer roles. See the [instructions](https://infrastructure.2i2c.org/sre-guide/support/grafana-account) for how to invite others to join Grafana.
 
 ## Using Grafana for your JupyterHub
 
@@ -26,10 +26,17 @@ This Grafana account is separate from the account used to log into JupyterHub. T
 The "Activity" Grafana dashboard.
 :::
 
-There is work-in-progress documentation available about what each dashboard or panel represents in the upstream [JupyterHub Grafana](https://jupyterhub-grafana.readthedocs.io/en/latest/) project. You can also hover over the {octicon}`info` icon in the top-right corner of each panel for more information.
+There is work-in-progress documentation available about what each dashboard or panel represents in the upstream [JupyterHub Grafana Dashboards](https://jupyterhub-grafana.readthedocs.io/en/latest/) project. You can also hover over the {octicon}`info` icon in the top-right corner of each panel for more information.
 
 ## Making changes to Grafana dashboards
 
-Changes to the `JupyterHub dashboard` directory will not persist. If changes are required on a persistent basis, we encourage you to contribute to the upstream [jupyterhub/grafana-dashboards](https://github.com/jupyterhub/grafana-dashboards) project.
+If you make any changes to the pre-configured dashboards in the *JupyterHub Default Dashboards* and *Cloud Cost Dashboards* folders, then they will not be saved.
 
-Hub Champions are welcome to create their own custom dashboards and panel in a separate directory, but the configuration will not be backed up.
+We encourage you to create new dashboards outside of these folders (however the configurations will not be backed up), or even contribute to:
+
+- the upstream [https://github.com/jupyterhub/grafana-dashboards](https://github.com/jupyterhub/grafana-dashboards) project for *JupyterHub Default Dashboards*
+- the [https://github.com/2i2c-org/jupyterhub-cost-monitoring](https://github.com/2i2c-org/jupyterhub-cost-monitoring) project for *Cloud Cost Dashboards*
+
+## Resources
+
+Grafana is a powerful open source data visualization tool with many features. For more information on how to use Grafana, refer to the [Grafana documentation](https://grafana.com/docs/grafana/latest/).

admin/howto/monitoring/grafana-dashboards.md

@@ -1,10 +1,16 @@
-# Usage monitoring
+# Usage and cost monitoring
 
 This section describes how to monitor the usage of your hub. Note that not all features are available for all hubs – please [contact us](/support) if you would like to discuss enabling a feature for your community with us.
 
 ```{toctree}
 :maxdepth: 1
 grafana-dashboards
+cost-general
+cost-users
+reporting
 prometheus-access
-cost-attribution
 ```
+
+## Feedback and support
+
+If you have any feedback or suggestions on what works well or how you would like to improve usage monitoring, feel free to [open a GitHub issue](https://github.com/2i2c-org/jupyterhub-cost-monitoring/issues/new) or contact [support](/support.md)!

admin/howto/monitoring/index.md

@@ -2,9 +2,7 @@
 
 ## Overview
 
-Grafana is an open-source analytics and interactive visualization web application. Prometheus is an open-source monitoring and alerting platform that collects and stores metrics as time-series data, which feeds into Grafana as a data source.
-
-Grafana dashboard deployments for 2i2c hubs (k8s+JupyterHub) follow the templates outlined in the upstream [JupyterHub GitHub repository](https://github.com/jupyterhub/grafana-dashboards). Note that Prometheus data is retained for up to 3 years on 2i2c hubs.
+Grafana is an open-source analytics and interactive visualization web application. However the datasource is fetched from Prometheus, an open-source monitoring and alerting platform that collects and stores metrics in a time series database.
 
 ## Prerequisites
 

admin/howto/monitoring/prometheus-access.md

@@ -0,0 +1,26 @@
+# Sharing and reporting Grafana dashboards
+
+Grafana dashboards can be shared with other community members and stakeholders so they can understand usage and cost patterns. Community Champions can
+
+- export data to a CSV file
+- generate a snapshot of the Grafana dashboard and share a public link
+- or even [Programmatically access Prometheus data](prometheus-access.md) themselves.
+
+## Generate a CSV file
+
+1. Click on the three dots {material-regular}`more_vert`, in the top-right corner of the panel you wish to generate a CSV file for.
+1. From the dropdown menu select *{octicon}`info` Inspect > Data*.
+1. Click on the {bdg-primary}`Download CSV` button to download the data as a CSV file.
+
+## Share a snapshot of the dashboard or panel
+
+This function is available to Grafana admins only. A snapshot is a frozen view of data that can with others without the need to login with a Grafana account.
+
+1. If you wish to share the *entire dashboard*, click on the {bdg-primary}`Share` button to the left of the time-range selector.
+1. If you wish to share a *single panel*, click on the three dots {material-regular}`more_vert`, in the top-right corner of a panel. From the dropdown menu select *Share*.
+1. From the pop-up *Share Panel* dialog, select the *Snapshot* tab and fill out the details.
+1. Click the {bdg-primary}`Publish Snapshot` button to generate a public link that you can share with others.
+
+:::{figure} images/cost-attribution-snapshot.png
+:alt: Snapshot of the share panel dialog, with Snapshot name, Expire and Timeout fields.
+:::