tencent cloud

Service Registry and Governance

DocumentationService Registry and GovernancePolaris Java Application DevelopmentUsing the Java SDKObservability

Observability

PDF
Focus Mode
Font Size
Last updated: 2026-05-07 18:12:23

Scenarios

This document describes how to develop a Java application locally, access Polaris (North Star) via the polaris-sdk, and implement the observability feature.

Prerequisite

Before development, please ensure you have downloaded and installed Java and Maven.

Operation Steps

Step 1: Introduce Polaris Dependencies

1. Introduce the polaris sdk Dependency

Modify the pom.xml in the application's root directory to add dependencyManagement for polaris-java:
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
Note:
For polaris-sdk version information, see: Version Information.

2. Introduce polaris starter

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

Step 2: Add Polaris Configuration File polaris.yml

1. Create a polaris.yml file in the project's main/resources directory to initialize the polaris-java SDK.
2. Configure the application name, polaris (North Star) server IP address, and other information in the polaris.yml file. For server IP address details, refer to: Engine Management > Client Access Address.
global:
  serverConnectors:
    - id: polaris
      protocol: grpc
      addresses:
        # The IP address needs to be replaced with the client access IP address of the North Star engine you created.
        - 127.0.0.1:8091
  # Description: Configuration related to monitoring and log data reporting
  statReporter:
    # Description: Whether to Enable Reporting
    enable: true
    plugin:
      prometheus:
        type: push
        # Description: Configure the pushgateway IP address, effective only when type == push
        # The IP address needs to be replaced with the client access IP address of the North Star engine you created.
        address: 127.0.0.1:9091
        # Description: Set the execution interval for pushing metric data to pushgateway
        # Range: [1s:...], Default value: 10s
        pushInterval: 10s
For more polaris.yml configuration information, see default-config.yml.

Step 3: Application Development, Report Monitoring Metrics

Initiate the Call and Report the Request Call Result.

1. Initialize the ConsumerAPI SDK instance:
import com.tencent.polaris.factory.api.DiscoveryAPIFactory;

public static void main(String[] args) throws Exception {
    ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();
}
2. Set service invocation result information:
public enum RetStatus {
    // Service invocation successful
    RetSuccess,
    // Service invocation failed
    RetFail,
    // Service invocation timeout
    RetTimeout,
}

ServiceCallResult result = new ServiceCallResult();
// Set the callee service namespace
result.setNamespace(String namespace);
// Set the callee service information
result.setService(String service);
// Set callee instance
result.setInstance(Instance instance);
// Set the response code for this request
result.setRetCode(String code);
// Set the latency for this request
result.setDelay(String delay);
// Set the result status of this request
result.setRetStatus(RetStatus status);
// Set the request Tag for this request, format is key=value;key=value;
result.setLabels(String labels);
// Set the method to invoke for this request
result.setMethod(String method);
3. Report request invocation result:
After initializing the ServiceCallResult struct based on the request invocation context, you only need to call the ConsumerAPI.updateServiceCallResult method to report the request invocation results. The SDK internally converts the reported invocation result information into corresponding traffic invocation metric data and reports it to prometheus.
consumerAPI.updateServiceCallResult(ServiceCallResult)

Previous Topic: Configuration ManagementNext Topic: Second-Level Addressing

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback