Repository navigation
custom metrics API: simplification suggestion #2333
Description
Suggestion:
Remove the Metric class and have MetricDescriptor settable on CreateTimeSeriesRequest - or something similar.
Background:
Based on the user guide to create custom metrics, I have to create a MetricDescriptor:
final MetricServiceClient client = MetricServiceClient.create();
ProjectName name = ProjectName.create(projectId);
MetricDescriptor descriptor = MetricDescriptor.newBuilder()
.setType(metricType)
.setDescription("This is a simple example of a custom metric.")
.setMetricKind(MetricDescriptor.MetricKind.GAUGE)
.setValueType(MetricDescriptor.ValueType.DOUBLE)
.build();
CreateMetricDescriptorRequest request = CreateMetricDescriptorRequest.newBuilder()
.setNameWithProjectName(name)
.setMetricDescriptor(descriptor)
.build();
client.createMetricDescriptor(request);
Great, now I have a metricDescriptor. What can I do with it? Nothing really.
In order to write data, I'll need to create a TimeSeries, and that needs another representation of this metric/metricdescriptor called Metric:
// Prepares the metric descriptor
Metric metric = Metric.newBuilder()
.setType("custom.googleapis.com/my_metric")
.build();
...
// create time series
TimeSeries timeSeries = TimeSeries.newBuilder()
.setMetric(metric)
...
OKay, so I can't reuse the MetricDescriptor, I'll use Metric.
But then on the TimeSeries, I have .setMetricKind, .setMetricKindValue... I guess it is there so that if I create a TimeSeries without a MetricDescriptor first, the descriptor can be implicitly created. But then why introduce a separete class for it called Metric that doesn't even have the Kind, KindValue (~= ValueType? or just repetition?).
I find the situation confusing, as
- the difference between Metric and MetricDescriptor is unclear
- Metric related methods are lingering in the CreateTimeSeriesRequest
- the difference between CreateTimeSeriesRequest.setMetricKind and CreateTimeSeriesRequest.setMetricKindValue is unclear for first look...is it possible to get rid of setMetricKindValue?
I understand that this code is largely generated for now from the protobufs (#2331), I would offer this issue as an example where the user experience can be increased significantly and how the generated code is not user friendly by default.
Activity
garrettjonesgoogle commentedon Aug 16, 2017
@balopat could you update this issue with your current thoughts (given that we have had some internal discussions)?
balopat commentedon Aug 17, 2017
@garrettjonesgoogle, of course! Let me recap:
From the underlying API perspective there is not much that's expected to happen, and here are the summarized explanations (feel free to edit if I'm still missing something):
I accept that even though this terminology and relatively complex setup might not be to my liking but is unlikely to change (or only in next major versions with big features coming in) as it's well established deep in the API design.
I think that from a google-cloud-java perspective however, this issue still might be useful to highlight opportunities for improving the generator to lower the need for mental load required to learn the API as a Java developer:
yihanzhen commentedon Jan 12, 2018
This has been added to our feature backlog: https://github.com/GoogleCloudPlatform/google-cloud-java/wiki/Feature-backlog . This issue will be closed but is linked in the backlog and can continue to be used for comment and discussion.
fix: fix the write api integration test (#2333)
chore(deps): update dependency com.google.cloud:libraries-bom to v26.…
chore(deps): update dependency com.google.cloud:libraries-bom to v26.…
feat: add arithmetic expressions (#2333)
chore: remove unused image tag in .OwlBot-hermetic.yaml (googleapis#2333