dubbo/dubbo-spring-boot/dubbo-spring-boot-actuator

Dubbo Spring Boot Production-Ready

dubbo-spring-boot-actuator provides production-ready features (e.g. health checks, endpoints, and externalized configuration).

Content

1. Main Content
2. Integrate with Maven
3. Health Checks
4. Endpoints
5. Externalized Configuration

Integrate with Maven

You can introduce the latest dubbo-spring-boot-actuator to your project by adding the following dependency to your pom.xml

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-spring-boot-actuator</artifactId>
    <version>2.7.4.1</version>
</dependency>

If your project failed to resolve the dependency, try to add the following repository:

<repositories>
    <repository>
        <id>apache.snapshots.https</id>
        <name>Apache Development Snapshot Repository</name>
        <url>https://repository.apache.org/content/repositories/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Health Checks

dubbo-spring-boot-actuator supports the standard Spring Boot HealthIndicator as a production-ready feature , which will be aggregated into Spring Boot's Health and exported on HealthEndpoint that works MVC (Spring Web MVC) and JMX (Java Management Extensions) both if they are available.

Web Endpoint : /health

Suppose a Spring Boot Web application did not specify management.server.port, you can access http://localhost:8080/actuator/health via Web Client and will get a response with JSON format is like below :

{
  "status": "UP",
  "dubbo": {
    "status": "UP",
    "memory": {
      "source": "management.health.dubbo.status.defaults",
      "status": {
        "level": "OK",
        "message": "max:3641M,total:383M,used:92M,free:291M",
        "description": null
      }
    },
    "load": {
      "source": "management.health.dubbo.status.extras",
      "status": {
        "level": "OK",
        "message": "load:1.73583984375,cpu:8",
        "description": null
      }
    },
    "threadpool": {
      "source": "management.health.dubbo.status.extras",
      "status": {
        "level": "OK",
        "message": "Pool status:OK, max:200, core:200, largest:0, active:0, task:0, service port: 12345",
        "description": null
      }
    },
    "server": {
      "source": "dubbo@ProtocolConfig.getStatus()",
      "status": {
        "level": "OK",
        "message": "/192.168.1.103:12345(clients:0)",
        "description": null
      }
    }
  }
  // ignore others
}

memory, load, threadpool and server are Dubbo's build-in StatusCheckers in above example. Dubbo allows the application to extend StatusChecker's SPI.

Default , memory and load will be added into Dubbo's HealthIndicator , it could be overridden by externalized configuration StatusChecker's defaults.

JMX Endpoint : Health

Health is a JMX (Java Management Extensions) Endpoint with ObjectName org.springframework.boot:type=Endpoint,name=Health , it can be managed by JMX agent ,e.g. JDK tools : jconsole and so on.

Build-in StatusCheckers

META-INF/dubbo/internal/org.apache.dubbo.common.status.StatusChecker declares Build-in StatusCheckers as follow :

registry=org.apache.dubbo.registry.status.RegistryStatusChecker
spring=org.apache.dubbo.config.spring.status.SpringStatusChecker
datasource=org.apache.dubbo.config.spring.status.DataSourceStatusChecker
memory=org.apache.dubbo.common.status.support.MemoryStatusChecker
load=org.apache.dubbo.common.status.support.LoadStatusChecker
server=org.apache.dubbo.rpc.protocol.dubbo.status.ServerStatusChecker
threadpool=org.apache.dubbo.rpc.protocol.dubbo.status.ThreadPoolStatusChecker

The property key that is name of StatusChecker can be a valid value of management.health.dubbo.status.* in externalized configuration.

Endpoints

Actuator endpoint dubbo supports Actuator Endpoints :

ID	Enabled	HTTP URI	HTTP Method	Description	Content Type
dubbo	true	/actuator/dubbo	GET	Exposes Dubbo's meta data	application/json
dubboproperties	true	/actuator/dubbo/properties	GET	Exposes all Dubbo's Properties	application/json
dubboservices	false	/actuator/dubbo/services	GET	Exposes all Dubbo's ServiceBean	application/json
dubboreferences	false	/actuator/dubbo/references	GET	Exposes all Dubbo's ReferenceBean	application/json
dubboconfigs	true	/actuator/dubbo/configs	GET	Exposes all Dubbo's *Config	application/json
dubboshutdown	false	/actuator/dubbo/shutdown	POST	Shutdown Dubbo services	application/json

Web Endpoints

/actuator/dubbo

/dubbo exposes Dubbo's meta data :

{
  "timestamp": 1516623290166,
  "versions": {
    "dubbo-spring-boot": "2.7.5",
    "dubbo": "2.7.5"
  },
  "urls": {
    "dubbo": "https://github.com/apache/dubbo/",
    "google-group": "dev@dubbo.apache.org",
    "github": "https://github.com/apache/dubbo-spring-boot-project",
    "issues": "https://github.com/apache/dubbo-spring-boot-project/issues",
    "git": "https://github.com/apache/dubbo-spring-boot-project.git"
  }
}

/actuator/dubbo/properties

/actuator/dubbo/properties exposes all Dubbo's Properties from Spring Boot Externalized Configuration (a.k.a PropertySources) :

{
  "dubbo.application.id": "dubbo-provider-demo",
  "dubbo.application.name": "dubbo-provider-demo",
  "dubbo.application.qos-enable": "false",
  "dubbo.application.qos-port": "33333",
  "dubbo.protocol.id": "dubbo",
  "dubbo.protocol.name": "dubbo",
  "dubbo.protocol.port": "12345",
  "dubbo.registry.address": "N/A",
  "dubbo.registry.id": "my-registry",
  "dubbo.scan.basePackages": "org.apache.dubbo.spring.boot.sample.provider.service"
}

The structure of JSON is simple Key-Value format , the key is property name as and the value is property value.

/actuator/dubbo/services

/actuator/dubbo/services exposes all Dubbo's ServiceBean that are declared via <dubbo:service/> or @Service present in Spring ApplicationContext :

{
  "ServiceBean@org.apache.dubbo.spring.boot.sample.api.DemoService#defaultDemoService": {
    "accesslog": null,
    "actives": null,
    "cache": null,
    "callbacks": null,
    "class": "org.apache.dubbo.config.spring.ServiceBean",
    "cluster": null,
    "connections": null,
    "delay": null,
    "document": null,
    "executes": null,
    "export": null,
    "exported": true,
    "filter": "",
    "generic": "false",
    "group": null,
    "id": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "interface": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "interfaceClass": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "layer": null,
    "listener": "",
    "loadbalance": null,
    "local": null,
    "merger": null,
    "mock": null,
    "onconnect": null,
    "ondisconnect": null,
    "owner": null,
    "path": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "proxy": null,
    "retries": null,
    "scope": null,
    "sent": null,
    "stub": null,
    "timeout": null,
    "token": null,
    "unexported": false,
    "uniqueServiceName": "org.apache.dubbo.spring.boot.sample.api.DemoService:1.0.0",
    "validation": null,
    "version": "1.0.0",
    "warmup": null,
    "weight": null,
    "serviceClass": "DefaultDemoService"
  }
}

The key is the Bean name of ServiceBean , ServiceBean's properties compose value.

/actuator/dubbo/references

/actuator/dubbo/references exposes all Dubbo's ReferenceBean that are declared via @Reference annotating on Field or Method :

{
  "private org.apache.dubbo.spring.boot.sample.api.DemoService org.apache.dubbo.spring.boot.sample.consumer.controller.DemoConsumerController.demoService": {
    "actives": null,
    "cache": null,
    "callbacks": null,
    "class": "org.apache.dubbo.config.spring.ReferenceBean",
    "client": null,
    "cluster": null,
    "connections": null,
    "filter": "",
    "generic": null,
    "group": null,
    "id": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "interface": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "interfaceClass": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "layer": null,
    "lazy": null,
    "listener": "",
    "loadbalance": null,
    "local": null,
    "merger": null,
    "mock": null,
    "objectType": "org.apache.dubbo.spring.boot.sample.api.DemoService",
    "onconnect": null,
    "ondisconnect": null,
    "owner": null,
    "protocol": null,
    "proxy": null,
    "reconnect": null,
    "retries": null,
    "scope": null,
    "sent": null,
    "singleton": true,
    "sticky": null,
    "stub": null,
    "stubevent": null,
    "timeout": null,
    "uniqueServiceName": "org.apache.dubbo.spring.boot.sample.api.DemoService:1.0.0",
    "url": "dubbo://localhost:12345",
    "validation": null,
    "version": "1.0.0",
    "invoker": {
      "class": "org.apache.dubbo.common.bytecode.proxy0"
    }
  }
}

The key is the string presentation of @Reference Field or Method , ReferenceBean's properties compose value.

/actuator/dubbo/configs

/actuator/dubbo/configs exposes all Dubbo's *Config :

{
  "ApplicationConfig": {
    "dubbo-consumer-demo": {
      "architecture": null,
      "class": "org.apache.dubbo.config.ApplicationConfig",
      "compiler": null,
      "dumpDirectory": null,
      "environment": null,
      "id": "dubbo-consumer-demo",
      "logger": null,
      "name": "dubbo-consumer-demo",
      "organization": null,
      "owner": null,
      "version": null
    }
  },
  "ConsumerConfig": {
    
  },
  "MethodConfig": {
    
  },
  "ModuleConfig": {
    
  },
  "MonitorConfig": {
    
  },
  "ProtocolConfig": {
    "dubbo": {
      "accepts": null,
      "accesslog": null,
      "buffer": null,
      "charset": null,
      "class": "org.apache.dubbo.config.ProtocolConfig",
      "client": null,
      "codec": null,
      "contextpath": null,
      "dispatcher": null,
      "dispather": null,
      "exchanger": null,
      "heartbeat": null,
      "host": null,
      "id": "dubbo",
      "iothreads": null,
      "name": "dubbo",
      "networker": null,
      "path": null,
      "payload": null,
      "port": 12345,
      "prompt": null,
      "queues": null,
      "serialization": null,
      "server": null,
      "status": null,
      "telnet": null,
      "threadpool": null,
      "threads": null,
      "transporter": null
    }
  },
  "ProviderConfig": {
    
  },
  "ReferenceConfig": {
    
  },
  "RegistryConfig": {
    
  },
  "ServiceConfig": {
    
  }
}

The key is the simple name of Dubbo *Config Class , the value is*Config Beans' Name-Properties Map.

/actuator/dubbo/shutdown

/actuator/dubbo/shutdown shutdowns Dubbo's components including registries, protocols, services and references :

{
    "shutdown.count": {
        "registries": 0,
        "protocols": 1,
        "services": 0,
        "references": 1
    }
}

"shutdown.count" means the count of shutdown of Dubbo's components , and the value indicates how many components have been shutdown.

Externalized Configuration

StatusChecker Defaults

management.health.dubbo.status.defaults is a property name for setting names of StatusCheckers , its value is allowed to multiple-values , for example :

management.health.dubbo.status.defaults = registry,memory,load

Default Value

The default value is :

management.health.dubbo.status.defaults = memory,load

StatusChecker Extras

management.health.dubbo.status.extras is used to override the [StatusChecker's defaults] , the multiple-values is delimited by comma :

management.health.dubbo.status.extras = load,threadpool

Health Checks Enabled

management.health.dubbo.enabled is a enabled configuration to turn on or off health checks feature, its' default is true.

If you'd like to disable health checks , you could apply management.health.dubbo.enabled to be false:

management.health.dubbo.enabled = false

Endpoints Enabled

Dubbo Spring Boot providers actuator endpoints , however some of them are disable. If you'd like to enable them , please add following properties into externalized configuration :

# Enables Dubbo All Endpoints
management.endpoint.dubbo.enabled = true
management.endpoint.dubboshutdown.enabled = true
management.endpoint.dubboconfigs.enabled = true
management.endpoint.dubboservices.enabled = true
management.endpoint.dubboreferences.enabled = true
management.endpoint.dubboproperties.enabled = true