Skip to content

Commit

Permalink
docs(): add doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@Rawven
Rawven committed Oct 23, 2024
1 parent c172d6c commit da51124
Show file tree
Hide file tree
Showing 7 changed files with 149 additions and 547 deletions.
Binary file added doc/images/apollo-client-monitor-jmx.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/images/apollo-client-monitor-prometheus.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/images/img.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
234 changes: 1 addition & 233 deletions docs/en/client/java-sdk-user-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -414,24 +414,6 @@ The configuration methods, in descending order of priority, are
3. Via the `app.properties` configuration file
* You can specify `apollo.override-system-properties=true` in `classpath:/META-INF/app.properties`

### 1.2.4.9 Monitor-related Configuration

> Applicable for version 2.4.0 and above
Starting from version 2.4.0, the observability of the client has been enhanced. Users can obtain the client status information directly through ConfigService by accessing ConfigMonitor and report the status as metrics to monitoring systems. Below are some related configurations.

`apollo.client.monitor.enabled`: Enables the Monitor mechanism, i.e., whether ConfigMonitor is activated. The default is false.

`apollo.client.monitor.jmx.enabled`: Exposes Monitor data in JMX format. If enabled, tools like J-console and Jprofiler can be used to view the relevant information. The default is false.

`apollo.client.monitor.exception-queue-size`: Sets the maximum number of exceptions that the Monitor can store. The default value is 25.

`apollo.client.monitor.external.type`: **Non-standard configuration item**, used to activate the corresponding monitoring system's Exporter when exporting metric data. For example, if the apollo-plugin-client-prometheus is introduced, "prometheus" can be specified to enable it. The values available for configuration depend on the MetricsExporter SPI introduced (official or custom implementations). This design allows for easy extensibility. If multiple, incorrect, or no values are set, no Exporter will be enabled.

For specific usage, see the section on Extension Development - Java Client Access to Different Monitoring Systems.

`apollo.client.monitor.external.export-period`: The Exporter exports status information (e.g., thread pools) from the Monitor and converts it into metric data through scheduled tasks. The export-period controls the frequency of these scheduled tasks. The default is 10 seconds.


# II. Maven Dependency

Apollo's client jar package has been uploaded to the central repository, the application only needs to be introduced in the following way when it is actually used.
Expand Down Expand Up @@ -468,8 +450,6 @@ Apollo supports API approach and Spring integration approach, how to choose whic

* For more interesting practical usage scenarios and sample code, please refer to [apollo-use-cases](https://github.com/ctripcorp/apollo-use-cases)



## 3.1 API Usage

The API approach is the easiest and most efficient way to use Apollo configuration without relying on the Spring Framework to use it.
Expand Down Expand Up @@ -539,207 +519,6 @@ String someNamespace = "test";
ConfigFile configFile = ConfigService.getConfigFile("test", ConfigFileFormat.XML);
String content = configFile.getContent();
```
### 3.1.5 Using the Monitor Feature

In version 2.4.0, apollo-client significantly enhanced observability by providing the ConfigMonitor API and metrics export options for JMX and Prometheus.

To enable the monitor feature, you need to configure apollo.client.monitor.enabled to true.


```yaml
apollo:
client:
monitor:
enabled: true
```

#### 3.1.5.1 Exposing Status Information via JMX

Enable apollo.client.monitor.jmx.enabled in the configuration.

```yaml
apollo:
client:
monitor:
enabled: true
jmx:
enabled: true
```

After starting the application, you can view it using J-console or J-profiler; here, we use J-profiler as an example.

![](https://raw.githubusercontent.com/Rawven/image/main/20241020224657.png)

#### 3.1.5.2 Exporting Metrics via Prometheus

Introduce the official dependency package
```xml
<dependency>
<groupId>com.ctrip.framework.apollo</groupId>
<artifactId>apollo-plugin-client-prometheus</artifactId>
<version>2.4.0-SNAPSHOT</version>
</dependency>
```
Adjust the configuration apollo.client.monitor.external.type=prometheus
```yaml
apollo:
client:
monitor:
enabled: true
external:
type: prometheus
```

This allows you to obtain ExporterData through ConfigMonitor (the format depends on the monitoring system you configured), and then expose the endpoint to Prometheus.


Example code

```java
@RestController
@ResponseBody
public class TestController {

@GetMapping("/metrics")
public String metrics() {
ConfigMonitor configMonitor = ConfigService.getConfigMonitor();
return configMonitor.getExporterData();
}
}
```

After starting the application, let Prometheus listen to this interface, and you will see request logs with a similar format.
```
# TYPE apollo_client_thread_pool_active_task_count gauge
# HELP apollo_client_thread_pool_active_task_count apollo gauge metrics
apollo_client_thread_pool_active_task_count{thread_pool_name="RemoteConfigRepository"} 0.0
apollo_client_thread_pool_active_task_count{thread_pool_name="AbstractApolloClientMetricsExporter"} 1.0
apollo_client_thread_pool_active_task_count{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_active_task_count{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_namespace_timeout gauge
# HELP apollo_client_namespace_timeout apollo gauge metrics
apollo_client_namespace_timeout 0.0
# TYPE apollo_client_thread_pool_pool_size gauge
# HELP apollo_client_thread_pool_pool_size apollo gauge metrics
apollo_client_thread_pool_pool_size{thread_pool_name="RemoteConfigRepository"} 1.0
apollo_client_thread_pool_pool_size{thread_pool_name="AbstractApolloClientMetricsExporter"} 1.0
apollo_client_thread_pool_pool_size{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_pool_size{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_thread_pool_queue_remaining_capacity gauge
# HELP apollo_client_thread_pool_queue_remaining_capacity apollo gauge metrics
apollo_client_thread_pool_queue_remaining_capacity{thread_pool_name="RemoteConfigRepository"} 2.147483647E9
apollo_client_thread_pool_queue_remaining_capacity{thread_pool_name="AbstractApolloClientMetricsExporter"} 2.147483647E9
apollo_client_thread_pool_queue_remaining_capacity{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_queue_remaining_capacity{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_exception_num counter
# HELP apollo_client_exception_num apollo counter metrics
apollo_client_exception_num_total 1404.0
apollo_client_exception_num_created 1.729435502796E9
# TYPE apollo_client_thread_pool_largest_pool_size gauge
# HELP apollo_client_thread_pool_largest_pool_size apollo gauge metrics
apollo_client_thread_pool_largest_pool_size{thread_pool_name="RemoteConfigRepository"} 1.0
apollo_client_thread_pool_largest_pool_size{thread_pool_name="AbstractApolloClientMetricsExporter"} 1.0
apollo_client_thread_pool_largest_pool_size{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_largest_pool_size{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_thread_pool_queue_size gauge
# HELP apollo_client_thread_pool_queue_size apollo gauge metrics
apollo_client_thread_pool_queue_size{thread_pool_name="RemoteConfigRepository"} 352.0
apollo_client_thread_pool_queue_size{thread_pool_name="AbstractApolloClientMetricsExporter"} 0.0
apollo_client_thread_pool_queue_size{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_queue_size{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_namespace_usage counter
# HELP apollo_client_namespace_usage apollo counter metrics
apollo_client_namespace_usage_total{namespace="application"} 11.0
apollo_client_namespace_usage_created{namespace="application"} 1.729435502791E9
# TYPE apollo_client_thread_pool_core_pool_size gauge
# HELP apollo_client_thread_pool_core_pool_size apollo gauge metrics
apollo_client_thread_pool_core_pool_size{thread_pool_name="RemoteConfigRepository"} 1.0
apollo_client_thread_pool_core_pool_size{thread_pool_name="AbstractApolloClientMetricsExporter"} 1.0
apollo_client_thread_pool_core_pool_size{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_core_pool_size{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_namespace_not_found gauge
# HELP apollo_client_namespace_not_found apollo gauge metrics
apollo_client_namespace_not_found 351.0
# TYPE apollo_client_thread_pool_total_task_count gauge
# HELP apollo_client_thread_pool_total_task_count apollo gauge metrics
apollo_client_thread_pool_total_task_count{thread_pool_name="RemoteConfigRepository"} 353.0
apollo_client_thread_pool_total_task_count{thread_pool_name="AbstractApolloClientMetricsExporter"} 4.0
apollo_client_thread_pool_total_task_count{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_total_task_count{thread_pool_name="AbstractConfig"} 0.0
# TYPE apollo_client_namespace_first_load_time_spend_in_ms gauge
# HELP apollo_client_namespace_first_load_time_spend_in_ms apollo gauge metrics
apollo_client_namespace_first_load_time_spend_in_ms{namespace="application"} 108.0
# TYPE apollo_client_thread_pool_maximum_pool_size gauge
# HELP apollo_client_thread_pool_maximum_pool_size apollo gauge metrics
apollo_client_thread_pool_maximum_pool_size{thread_pool_name="RemoteConfigRepository"} 2.147483647E9
apollo_client_thread_pool_maximum_pool_size{thread_pool_name="AbstractApolloClientMetricsExporter"} 2.147483647E9
apollo_client_thread_pool_maximum_pool_size{thread_pool_name="AbstractConfigFile"} 2.147483647E9
apollo_client_thread_pool_maximum_pool_size{thread_pool_name="AbstractConfig"} 2.147483647E9
# TYPE apollo_client_namespace_item_num gauge
# HELP apollo_client_namespace_item_num apollo gauge metrics
apollo_client_namespace_item_num{namespace="application"} 9.0
# TYPE apollo_client_thread_pool_completed_task_count gauge
# HELP apollo_client_thread_pool_completed_task_count apollo gauge metrics
apollo_client_thread_pool_completed_task_count{thread_pool_name="RemoteConfigRepository"} 1.0
apollo_client_thread_pool_completed_task_count{thread_pool_name="AbstractApolloClientMetricsExporter"} 3.0
apollo_client_thread_pool_completed_task_count{thread_pool_name="AbstractConfigFile"} 0.0
apollo_client_thread_pool_completed_task_count{thread_pool_name="AbstractConfig"} 0.0
# EOF
```

You can also see similar information on the Prometheus console.

![](https://raw.githubusercontent.com/Rawven/image/main/20240922125033.png)

#### 3.1.5.3 Manually Calling the ConfigMonitor API to Retrieve Related Data (for example, when users need to manually process data to report to the monitoring system)

```java
ConfigMonitor configMonitor = ConfigService.getConfigMonitor();
// Error related monitoring API
ApolloClientExceptionMonitorApi exceptionMonitorApi = configMonitor.getExceptionMonitorApi();
List<Exception> apolloConfigExceptionList = exceptionMonitorApi.getApolloConfigExceptionList();
// Namespace related monitoring API
ApolloClientNamespaceMonitorApi namespaceMonitorApi = configMonitor.getNamespaceMonitorApi();
List<String> namespace404 = namespaceMonitorApi.getNotFoundNamespaces();
// Startup parameter related monitoring API
ApolloClientBootstrapArgsMonitorApi runningParamsMonitorApi = configMonitor.getRunningParamsMonitorApi();
String bootstrapNamespaces = runningParamsMonitorApi.getBootstrapNamespaces();
// Thread pool related monitoring API
ApolloClientThreadPoolMonitorApi threadPoolMonitorApi = configMonitor.getThreadPoolMonitorApi();
ApolloThreadPoolInfo remoteConfigRepositoryThreadPoolInfo = threadPoolMonitorApi.getRemoteConfigRepositoryThreadPoolInfo();
```

#### 3.1.5.4 Metrics Data Table

## Namespace Metrics

| Metric Name | Tags |
|-----------------------------------------------------|-----------|
| apollo_client_namespace_usage_total | namespace |
| apollo_client_namespace_item_num | namespace |
| apollo_client_namespace_not_found | |
| apollo_client_namespace_timeout | |
| apollo_client_namespace_first_load_time_spend_in_ms | namespace |

## Thread Pool Metrics

| Metric Name | Tags |
| -------------------------------------------------- | ---------------- |
| apollo_client_thread_pool_pool_size | thread_pool_name |
| apollo_client_thread_pool_maximum_pool_size | thread_pool_name |
| apollo_client_thread_pool_largest_pool_size | thread_pool_name |
| apollo_client_thread_pool_completed_task_count | thread_pool_name |
| apollo_client_thread_pool_queue_remaining_capacity | thread_pool_name |
| apollo_client_thread_pool_total_task_count | thread_pool_name |
| apollo_client_thread_pool_active_task_count | thread_pool_name |
| apollo_client_thread_pool_core_pool_size | thread_pool_name |
| apollo_client_thread_pool_queue_size | thread_pool_name |

## Exception Metrics

| Metric Name | Tags |
| --------------------------------- | ---- |
| apollo_client_exception_num_total | |

## 3.2 Spring integration approach

Expand Down Expand Up @@ -1502,15 +1281,4 @@ The interface is `com.ctrip.framework.apollo.spi.ConfigServiceLoadBalancerClient
The Input is multiple ConfigServices returned by meta server, and the output is a ConfigService selected.
The default service provider is `com.ctrip.framework.apollo.spi.RandomConfigServiceLoadBalancerClient`, which chooses one ConfigService from multiple ConfigServices using random strategy .
## 7.2 MetricsExporter Extension
> from version 2.4.0
To meet users' varying system requirements for metrics exporting (e.g., Prometheus, Skywalking) when using apollo-client, we have provided an SPI in the enhanced observability of version 2.4.0.

The interface is com.ctrip.framework.apollo.monitor.internal.exporter.ApolloClientMetricsExporter.

We offer an abstract class for a general metrics export framework, com.ctrip.framework.apollo.monitor.internal.exporter.AbstractApolloClientMetricsExporter. You just need to extend this class and implement the relevant methods to customize integration with other monitoring systems. You can refer to the implementation of apollo-plugin-client-prometheus.

By default, there are no services provided, which means no metrics data will be exported.
The default service provider is `com.ctrip.framework.apollo.spi.RandomConfigServiceLoadBalancerClient`, which chooses one ConfigService from multiple ConfigServices using random strategy .
Loading

0 comments on commit da51124

Please sign in to comment.