[FINAL] feat: Add sections for new subnet_info endpoint

[michael-weigelt]

In certain circumstances, canisters wish to learn about subnet-specific data or metadata. This endpoint enables these use cases, starting with exposing the replica version a subnet is currently running.

Open questions:

• Should this method be restricted to canisters or can any principal call it? Update: Yes, to pass on the cost to the caller
• Naming: Is 'stats' fine if we anticipate that data like number of canisters, memory occupied etc might be added to the response struct? Update: Renamed to subnet_metrics Update Renaming to subnet_info!

[github-actions]

🤖 Here's your preview: https://pjpim-riaaa-aaaak-qckja-cai.icp0.io/docs

[mraszyk]

LGTM

[adambratschikaye]

If a canister wants to get the information for it's own subnet, how is it supposed to figure out which subnet it is on?

[mraszyk]

If a canister wants to get the information for it's own subnet, how is it supposed to figure out which subnet it is on?

The registry has an endpoint that serves this information.

[dsarlis]

Is there a reason why we went with subnet_metrics instead of subnet_metadata or subnet_info? The replica_version is not exactly a metric. Do we envision that we would eventually have things like number of canisters or state of the subnet served through this endpoint? Even then, I think subnet_info would still be ok (subnet_metrics would still suffer from including the replica_version which is not really a metric).

[michael-weigelt]

Do we envision that we would eventually have things like number of canisters or state of the subnet served through this endpoint

Yes, I believe. But I see the point. It's a misnomer now, and will be less of a misnomer later, but still not quite right.

why

Just in case you missed the collapsed item.

[mraszyk]

Is there a reason why we went with subnet_metrics instead of subnet_metadata or subnet_info? The replica_version is not exactly a metric. Do we envision that we would eventually have things like number of canisters or state of the subnet served through this endpoint? Even then, I think subnet_info would still be ok (subnet_metrics would still suffer from including the replica_version which is not really a metric).

I agree that subnet_info makes more sense and is consistent with the existing canister_info endpoint. We already have a path /subnet/<subnet_id>/metrics in the state tree though and if we eventually converge into having the same data in the state tree and in subnet_info, then the name would be inconsistent (unless we could rename the state tree path).

[dsarlis]

Is there a reason why we went with subnet_metrics instead of subnet_metadata or subnet_info? The replica_version is not exactly a metric. Do we envision that we would eventually have things like number of canisters or state of the subnet served through this endpoint? Even then, I think subnet_info would still be ok (subnet_metrics would still suffer from including the replica_version which is not really a metric).

I agree that subnet_info makes more sense and is consistent with the existing canister_info endpoint. We already have a path /subnet/<subnet_id>/metrics in the state tree though and if we eventually converge into having the same data in the state tree and in subnet_info, then the name would be inconsistent (unless we could rename the state tree path).

The state tree path contains only metrics for now so that is consistent imo. If we want to unify at some point (the two return a different set of information for now), then we can switch to subnet_info for the state tree path too. (Likely by introducing a new path that supersedes the old for backward compatibility).

[Dfinity-Bjoern]

I am also fine with subnet_info, if that's the preferred term overall.

[michael-weigelt]

Thanks for the changes @mraszyk. Do we consider this PR final? @Dfinity-Bjoern
The implementation is updated, here.

[mraszyk]

Superseded by dfinity/portal#3755