Skip to content
Browse documentation

Get started

Getting startedSend your first metric

SDKs

SDK overviewJava SDKGo SDK

Metrics

Query metrics in the UIMetric rollups and resolution

Monitor

Create a dashboardCreate an alarmCreate notification channels

Workspace and access

Create an API tokenCreate and use rolesInvite users to a workspaceAccount settings and lifecycleManage workspaces

On this page

RequirementsConfigure authenticationCreate a clientSend a metricQuery metric dataHandle errorsNext steps

Java SDK

Install the Java metrics SDK, authenticate with an M2M credential, and send and query metrics with the synchronous client.

Markdown

The official Java SDK provides typed request builders, response models, validation, and API exceptions for the Metrics API. This guide uses the synchronous MetricsClient.

Use the API reference when you need the parameters and response schema for a specific operation.

Requirements

The SDK requires Java 17 or newer and is published to Maven Central. Add the metrics module to your Maven project:

<dependency>
    <groupId>cloud.omas.sdk</groupId>
    <artifactId>metrics</artifactId>
    <version>0.2.0</version>
</dependency>

The shared core module and its runtime dependencies are included transitively.

Configure authentication

Use an exchange-only M2M credential for a service, job, or other unattended workload. On the API tokens page, create a token and select Exchange only as its access mode. Store the credential in your secret manager and expose it to the process as OMAS_M2M_TOKEN; never commit it to source control.

M2mAuthProvider exchanges the credential for short-lived, metrics-scoped access tokens and refreshes them automatically. A token created in Direct mode is sent to service APIs as a bearer token and is not the credential this provider expects.

Create a client

Create the authentication provider and client once, reuse the client for requests, and close both when the application shuts down. Both types implement AutoCloseable, so try-with-resources is a good fit for short-lived programs:

import cloud.omas.sdk.core.M2mAuthProvider;
import cloud.omas.sdk.metrics.MetricsClient;
import cloud.omas.sdk.metrics.model.ListMetricsOperationRequest;
import cloud.omas.sdk.metrics.model.ListMetricsResponse;

try (M2mAuthProvider authProvider = M2mAuthProvider.builder()
        .credential(System.getenv("OMAS_M2M_TOKEN"))
        .build();
     MetricsClient metrics = MetricsClient.builder()
        .authProvider(authProvider)
        .build()) {
    ListMetricsResponse response = metrics.listMetrics(
            ListMetricsOperationRequest.builder()
                    .maxResults(25)
                    .build());

    response.metrics().forEach(metric -> System.out.println(metric.name()));
}

Reuse the authentication provider and client instead of creating new instances for every request.

Send a metric

Every SDK operation accepts one generated operation-request object. Request fields use immutable builder-based models:

import cloud.omas.sdk.metrics.model.DataPoint;
import cloud.omas.sdk.metrics.model.PutMetricDataOperationRequest;

import java.math.BigDecimal;
import java.util.List;

metrics.putMetricData(
        PutMetricDataOperationRequest.builder()
                .metricName("cpu_usage")
                .entries(List.of(DataPoint.builder()
                        .timestamp(System.currentTimeMillis())
                        .value(BigDecimal.valueOf(42.7))
                        .resolution(60)
                        .build()))
                .build());

See Send your first metric for dimensions and pre-aggregated statistic sets.

Query metric data

Pass Unix epoch milliseconds for the time range. The response contains the returned data points and pagination token:

import cloud.omas.sdk.metrics.model.GetMetricDataOperationRequest;
import cloud.omas.sdk.metrics.model.GetMetricDataResponse;

long endTimestamp = System.currentTimeMillis();
long startTimestamp = endTimestamp - 3_600_000L;

GetMetricDataOperationRequest request = GetMetricDataOperationRequest.builder()
        .metricName("cpu_usage")
        .startTimestamp(startTimestamp)
        .endTimestamp(endTimestamp)
        .resolution(60)
        .aggregation("avg")
        .build();

GetMetricDataResponse response = metrics.getMetricData(request);

Read Metric rollups and resolution before choosing an aggregation and resolution for production queries.

Handle errors

The SDK decodes documented API errors into typed exceptions. Catch a specific exception when the application can recover from that condition, then use ApiException as the common fallback for API responses:

import cloud.omas.sdk.core.exception.ApiException;
import cloud.omas.sdk.metrics.exception.ResourceNotFoundException;
import cloud.omas.sdk.metrics.model.GetMetricDataOperationRequest;

GetMetricDataOperationRequest request = GetMetricDataOperationRequest.builder()
        .metricName("cpu_usage")
        .startTimestamp(System.currentTimeMillis() - 3_600_000L)
        .build();

try {
    metrics.getMetricData(request);
} catch (ResourceNotFoundException exception) {
    System.err.println("Metric not found: " + exception.getMessage());
} catch (ApiException exception) {
    System.err.printf(
            "Metrics request failed: status=%d code=%s requestId=%s%n",
            exception.statusCode(),
            exception.errorCode(),
            exception.requestId());
}

Generated builders throw IllegalArgumentException for invalid input before a request is sent. Authentication, timeout, serialization, and transport failures use SDK exceptions from cloud.omas.sdk.core.exception. Log the request ID when it is available and retry only when the failure type and operation make that safe.

Next steps