Cloudsmith: add v2 bandwidth analytics and repository metrics by BartoszBlizniak · Pull Request #2917 · DataDog/integrations-extras

BartoszBlizniak · 2026-03-03T16:11:11Z

What does this PR do?

It introduces a new bandwidth analytics pipeline using the Cloudsmith v2 analytics time-series API, replacing the previous entitlements-based approach, and adds repository-level observability improvements.

This includes:

Org-wide realtime bandwidth monitoring
Controlled via enable_realtime_bandwidth (default true). Fetches total bytes downloaded and request count for the entire organization with no filters. Emits:
- cloudsmith.bandwidth.bytes_downloaded
- cloudsmith.bandwidth.request_count
Profile-based bandwidth monitoring
Users can define named bandwidth_profiles in their config, each with its own aggregate (bytes_downloaded_sum or request_count) and granular filters such as:
- repository
- package_format
- user
- entitlement_token
- ip_address
- http_status
- country
Each profile emits cloudsmith.analytics.bytes_downloaded_sum or cloudsmith.analytics.request_count tagged with profile:<name> plus all configured filter tags.
Repository-level observability
Adds repository data collection from Cloudsmith /repos/{owner}/ with pagination handling and emits:
- cloudsmith.repository.storage_bytes
- cloudsmith.repository.package_count
- cloudsmith.repository.download_count
Dashboard updates
Adds:
- Org Bandwidth Overview with query-value and timeseries widgets for org-wide metrics
- Profile-based widgets for drill-down by profile
- Repository Overview with selection query values and toplists for storage, package count, and download usage
Quota fix
Corrects slight margin errors in quota endpoint conversions.
Tests and docs updates
Adds unit test coverage for:
- bandwidth profile behavior
- repository pagination/parsing
- repository metric submission
Also updates:
- configuration spec
- example config
- README
- metadata
- changelog

Motivation

Cloudsmith users need both broader bandwidth observability and more granular attribution of usage.

The previous bandwidth implementation relied on the entitlements endpoint, which had limited filtering capability and did not support the level of granularity customers need. The Cloudsmith v2 analytics time-series API provides per-interval bucketed data with rich filtering dimensions such as repository, package format, user, entitlement token, IP address, and HTTP status, enabling customers to:

Monitor bandwidth consumption at the org level with zero configuration
Create targeted profiles to track specific repos, package formats, or user segments
Set alerts on bandwidth spikes or unusual download patterns for specific scopes
Attribute bandwidth costs to specific teams, tokens, or repositories

In addition, Cloudsmith users needed per-repository visibility into storage utilization and operational counters. The repository endpoint integration adds direct repository-level visibility for storage, package count, and download count, and makes those metrics explorable in Datadog dashboards using repository:<slug> tags.

Review checklist

PR has a meaningful title or PR has the no-changelog label attached
Feature or bugfix has tests
Git history is clean
If PR impacts documentation, docs team has been notified or an issue has been opened on the documentation repo
If this PR includes a log pipeline, please add a description describing the remappers and processors.

Additional Notes

Metric type: gauge
The integration submits the latest completed bucket value as a gauge. Each API data point represents bytes downloaded or request count in one interval bucket, which is treated as a point-in-time measurement for that window. The dedup logic ensures only one value is submitted per bucket, and explicit zeros are emitted when no new data is available so dashboards do not interpolate stale values.

New metrics

Metric	Type	Description
`cloudsmith.bandwidth.bytes_downloaded`	gauge	Org-wide total bytes downloaded per interval (no filters)
`cloudsmith.bandwidth.request_count`	gauge	Org-wide total request count per interval (no filters)
`cloudsmith.analytics.bytes_downloaded_sum`	gauge	Per-profile bytes downloaded per interval (with filter tags)
`cloudsmith.analytics.request_count`	gauge	Per-profile request count per interval (with filter tags)
`cloudsmith.repository.storage_bytes`	gauge	Current storage usage for a repository in bytes
`cloudsmith.repository.package_count`	gauge	Number of packages in the repository
`cloudsmith.repository.download_count`	gauge	Total package downloads for the repository

Configuration example

enable_realtime_bandwidth: true
bandwidth_interval: five_minutes
bandwidth_profiles:
  - name: prod-python
    aggregate: bytes_downloaded_sum
    repository:
      - production
    package_format:
      - python
    entitlement_token:
      - e2e

… plugin when ratelimit hits

…ion-has-stopped-receiving-metrics

…integration-has-stopped-receiving-metrics fix(CENG-719): Improve error handling around rate limits

git-thuerk-done

Hi @BartoszBlizniak just a couple of small corrections for the change log (typos and British spelling corrections), let me know when this is ready for re-review

Co-authored-by: Alicia Thuerk <alicia.thuerk@datadoghq.com>

…-datadog' of github.com:BartoszBlizniak/integrations-extras into ceng-726-create-metric-for-consumption-by-repository-in-datadog

dkirov-dd · 2026-03-10T11:28:41Z

+        # Dedup: only submit if this timestamp is newer than the last one we submitted.
+        last_submitted = self._profile_last_ts.get(dedup_key, 0)
+        if latest_ts_epoch <= last_submitted:
+            self.log.debug("No new data for %s; submitting zero.", label)


question/request
I find it odd/misleading to submit 0 when there is no new data.
Why would this be better than skipping the sumbission?

see below comment/response

dkirov-dd · 2026-03-10T11:31:36Z

+
+            if not self._should_poll_analytics(dedup_key):
+                # Keep metric continuity while avoiding unnecessary API calls.
+                self.gauge(metric_name, 0.0, tags=self.tags)


question/request
I find it odd/misleading to submit 0 in between polls.
Why would this be better than skipping the submission?

During my testing, I've observed that when a gauge is used, if no new data is present within, let's say, a 5-minute timeframe, the candles in the graph will keep reporting the last known value for the next 4-5 subsequent checks, which was throwing off the actual reporting in the given interval. The metrics API takes some time to properly propagate so I'm allowing some extra buffer time before submission to ensure that the value being reported matches closely with what we see in the UI usage logs. I was a bit confused as to what metric could be best here but this is the only way I figured in which the reporting was accurate.

For background, we report back:

{ "filters": { "start_time": "2026-02-27T14:07:50Z", "repository": [ { "name": "testing-private", "repository_type": "PRIVATE", "slug": "testing-private", } ], "aggregate": "BYTES_DOWNLOADED_SUM", "interval": "MINUTE" }, "results": [ { "dimensions": { "aggregate": "BYTES_DOWNLOADED_SUM", "unit": "bytes" }, "timestamps": [ "2026-02-27T14:16:00Z", "2026-02-27T14:19:00Z", "2026-02-27T14:54:00Z", "2026-02-27T14:56:00Z" ], "values": [570989513, 3090206893, 1027, 3090206893] } ] }

The values are the total number of bytes downloaded over a given time interval. We only want to upload the data once it's fully settled and only report in the Datadog entry, which has been submitted. Without submitting a 0, the last known value would be repeatedly inserted for next few checks.

For reference this is how it looks like in our UI dashboard:

Do you have any recommendations on how to best tackle this?

I see.
The interpolation/filling issue with missing data can be controlled from the Datadog UI.
You can apply a .fill(zero) or .fill(null) modifier to suppress interpolation. By default, gauges are displayed with a linear interpolation for a maximum of 5 minutes.

I think it would be better to not submit the 0 metrics in between polls. That way the user can configure how they would like the missing metrics to be displayed (zeros or null).
You can modify the dashboard widgets to utilize the .fill modifier.

Thanks @dkirov-dd - I'll pick this up on Monday again

Thank you once again @dkirov-dd for the feedback. I think you’re right. After looking at it more closely, the 0 we submit here does not actually mean “zero downloads in a completed interval” in most cases. It usually means “no new settled bucket yet” because the analytics API is delayed, the latest bucket is still incomplete, or we intentionally skipped polling/deduped the same timestamp.

The interpolation issue is still real, but that seems better handled at the Datadog query/widget layer with .fill(null) or .fill(zero) depending on what the user wants to see.

So I’m leaning toward keeping the settle/dedup logic, but skipping metric submission when there is no new completed bucket rather than emitting 0.

Hey @BartoszBlizniak,
That sounds good to me! 👌

dkirov-dd · 2026-03-10T11:34:35Z

-        # Submit realtime bandwidth gauge if present
-        if self.enable_realtime_bandwidth and realtime_metrics.get("bandwidth_bytes_interval") is not None:
-            self.gauge(
-                "cloudsmith.bandwidth_bytes_interval",


request
The bandwidth_bytes_interval metric is marked as deprecated in the metadata.csv but is no longer being collected at all.
Could you add back the logic for its collection?

…repository-in-datadog

…ion back

dkirov-dd · 2026-03-13T10:47:53Z

+cloudsmith.analytics.bytes_downloaded_sum,gauge,,byte,,"Total bytes downloaded in the configured analytics interval",0,cloudsmith,analytics_bytes_downloaded_sum,,profile
+cloudsmith.analytics.request_count,gauge,,item,,"Total download request count in the configured analytics interval",0,cloudsmith,analytics_request_count,,profile


Suggested change

cloudsmith.analytics.bytes_downloaded_sum,gauge,,byte,,"Total bytes downloaded in the configured analytics interval",0,cloudsmith,analytics_bytes_downloaded_sum,,profile

cloudsmith.analytics.request_count,gauge,,item,,"Total download request count in the configured analytics interval",0,cloudsmith,analytics_request_count,,profile

cloudsmith.analytics.bytes_downloaded_sum,gauge,,byte,,"Total bytes downloaded in the configured bandwidth interval",0,cloudsmith,analytics_bytes_downloaded_sum,,profile

cloudsmith.analytics.request_count,gauge,,item,,"Total download request count in the configured bandwidth interval",0,cloudsmith,analytics_request_count,,profile

Not sure if this is correct or not.
There is no analytics interval in the integration config.

You’re right, there isn’t a separate analytics_interval config in the integration. Updated the metadata text to say “configured collection interval” instead.

…repository-in-datadog

dkirov-dd · 2026-03-17T13:48:04Z

-cloudsmith.token_count,gauge,,item,,"The number of tokens in an organization",0,cloudsmith,token_count,,
-cloudsmith.token_bandwidth_total,gauge,,byte,,"The total bandwidth used by tokens",0,cloudsmith,token_bandwidth_total,,
-cloudsmith.token_download_total,gauge,,item,,"The total downloads used by tokens",0,cloudsmith,token_download_total,,


request
These metrics (cloudsmith.token_count, cloudsmith.token_bandwidth_total and cloudsmith.token_download_total) should continue being submitted even though we are deprecating them.
An update of the Cloudsmith integration would otherwise break dashboards for existing users.

P.S. don't forget to add them back in the tests too

My bad here, added those back. Just to confirm, we will be looking to deprecate these endpoints very soon, given we are setting warnings on this release, is it okay to fully remove those metrics in the following release? We will prepare notices on our end and send out notice to our customers about the change as well.

Thanks for adding the metrics back!

To answer your question, we prefer only deleting metrics when absolutely necessary.
We usually keep old metrics available under 'legacy' configuration options that users can enable if they are running an older version of the technology they want to monitor.

That being said, I'm not entirely up to date on Cloudsmith's offerings.
As far as I understand Cloudsmith is cloud only, i.e. when you deprecate the endpoints exposing the above metrics, this change will eventually affect all Cloudsmith users.
In that case I agree that the metrics could be removed in the future.

I would be against it if there were self-hosted versions of Cloudsmith which would allow users to be running different versions.

Perfect - and correct, we are fully cloud-native (no on-prem at all) so this will end up affceting our users. I don't have concrete timelines yet, but it's on the horizon as we're slowly sunsetting our legacy webapp to new stack which is using the new endpoints.

Perhaps towards the end of the year, I will be looking at re-creating the integration from the ground up as my team has officially taken over this project, or at a bare minimum, modularize it a bit to make contributions and reviews easier - for you folks and ourselves.

Appriciate the feedback and help 🙏

…ehaviour

davidfeng-datadog

LGTM

BartoszBlizniak and others added 13 commits February 25, 2026 12:56

Add ratelimit checks and improve error-handling to avoid crashing the…

5583a5b

… plugin when ratelimit hits

Merge branch 'DataDog:master' into ceng-719-thrivent-datadog-integrat…

bfe218d

…ion-has-stopped-receiving-metrics

Merge pull request #1 from BartoszBlizniak/ceng-719-thrivent-datadog-…

9caadee

…integration-has-stopped-receiving-metrics fix(CENG-719): Improve error handling around rate limits

Run lint fmt

ed732ac

add missing header to test

a5eb593

Merge branch 'DataDog:master' into master

e7e3211

Enchance analytics endpoint and deprecate old entitlement token endpoint

9b47db1

fix quota convertions

f9217b9

add to unreleased

e458a16

run validation

6e9e232

unit test add missing variable

a49f76c

further unit test fixes

33387f1

add repository storage information

7fbf936

BartoszBlizniak marked this pull request as ready for review March 3, 2026 16:24

BartoszBlizniak requested review from a team as code owners March 3, 2026 16:24

BartoszBlizniak requested a review from davidfeng-datadog March 3, 2026 16:24

rtrieu assigned rtrieu and unassigned rtrieu Mar 3, 2026

git-thuerk-done requested changes Mar 3, 2026

View reviewed changes

Comment thread cloudsmith/assets/configuration/spec.yaml Outdated

Comment thread cloudsmith/datadog_checks/cloudsmith/data/conf.yaml.example Outdated

Comment thread cloudsmith/CHANGELOG.md Outdated

Comment thread cloudsmith/CHANGELOG.md Outdated

Comment thread cloudsmith/CHANGELOG.md Outdated

BartoszBlizniak and others added 8 commits March 4, 2026 09:43

Update cloudsmith/assets/configuration/spec.yaml

51545e9

Co-authored-by: Alicia Thuerk <alicia.thuerk@datadoghq.com>

Update cloudsmith/datadog_checks/cloudsmith/data/conf.yaml.example

7b09b4c

Co-authored-by: Alicia Thuerk <alicia.thuerk@datadoghq.com>

Update cloudsmith/CHANGELOG.md

b335ba4

Co-authored-by: Alicia Thuerk <alicia.thuerk@datadoghq.com>

Update cloudsmith/CHANGELOG.md

b0604f7

Co-authored-by: Alicia Thuerk <alicia.thuerk@datadoghq.com>

Update cloudsmith/CHANGELOG.md

7ebd086

Co-authored-by: Alicia Thuerk <alicia.thuerk@datadoghq.com>

update example to 300s collection and readme update

d5f19ed

Merge branch 'ceng-726-create-metric-for-consumption-by-repository-in…

87dfa87

…-datadog' of github.com:BartoszBlizniak/integrations-extras into ceng-726-create-metric-for-consumption-by-repository-in-datadog

revert 300 to 15 in template

16eb3ac

temporal-github-worker-1 Bot removed the docs/approved label Mar 10, 2026

BartoszBlizniak requested a review from dd-dominic March 10, 2026 09:56

dkirov-dd requested changes Mar 10, 2026

View reviewed changes

temporal-github-worker-1 Bot added agent/requested-changes and removed agent/review-requested labels Mar 10, 2026

BartoszBlizniak and others added 2 commits March 12, 2026 12:51

Merge branch 'master' into ceng-726-create-metric-for-consumption-by-…

4f4c086

…repository-in-datadog

switch bandwidth metrics to off by default and add deprecated collect…

539de1d

…ion back

dkirov-dd reviewed Mar 13, 2026

View reviewed changes

BartoszBlizniak and others added 2 commits March 16, 2026 14:49

don't submit 0 on missing-data gauges

210785c

Merge branch 'master' into ceng-726-create-metric-for-consumption-by-…

45a40ce

…repository-in-datadog

BartoszBlizniak requested a review from dkirov-dd March 16, 2026 15:23

dkirov-dd requested changes Mar 17, 2026

View reviewed changes

add the deprecated resources back to the code to prevent unexpected b…

10b36c4

…ehaviour

dkirov-dd approved these changes Mar 18, 2026

View reviewed changes

temporal-github-worker-1 Bot added the agent/approved label Mar 18, 2026

gh-worker-ownership-write-b05516 Bot removed the request for review from dd-dominic March 18, 2026 10:37

temporal-github-worker-1 Bot removed the agent/requested-changes label Mar 18, 2026

dd-dominic approved these changes Mar 20, 2026

View reviewed changes

temporal-github-worker-1 Bot added product/approved and removed product/requested-changes labels Mar 20, 2026

git-thuerk-done approved these changes Mar 23, 2026

View reviewed changes

temporal-github-worker-1 Bot added docs/approved and removed docs/review-requested labels Mar 23, 2026

davidfeng-datadog approved these changes Mar 25, 2026

View reviewed changes

temporal-github-worker-1 Bot added ecosystems/approved and removed ecosystems/review-requested labels Mar 25, 2026

davidfeng-datadog added this pull request to the merge queue Mar 25, 2026

Merged via the queue into DataDog:master with commit 6455bcc Mar 25, 2026
35 checks passed

BartoszBlizniak mentioned this pull request Apr 14, 2026

Cloudsmith Release #2966

Open

		cloudsmith.analytics.bytes_downloaded_sum,gauge,,byte,,"Total bytes downloaded in the configured analytics interval",0,cloudsmith,analytics_bytes_downloaded_sum,,profile
		cloudsmith.analytics.request_count,gauge,,item,,"Total download request count in the configured analytics interval",0,cloudsmith,analytics_request_count,,profile

Conversation

BartoszBlizniak commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Review checklist

Additional Notes

Uh oh!

git-thuerk-done left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkirov-dd Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BartoszBlizniak Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidfeng-datadog left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

BartoszBlizniak commented Mar 3, 2026 •

edited

Loading

dkirov-dd Mar 17, 2026 •

edited

Loading

BartoszBlizniak Mar 18, 2026 •

edited

Loading