DOCSEARCHbyAlgolia
Submit Docs

SOFALookout Documentation

repository·master·Indexed 18 days ago

https://github.com/sofastack/sofa-lookout

A multi-dimensional metrics monitoring system based on the Metrics2.0 standard. It consists of a Java SDK for application-level metric collection and a server-side infrastructure for processing, storing, and visualizing metrics via Grafana and Elasticsearch. The system supports various metric types (Counter, Timer, DistributionSummary, Gauge, MixinMetric, TopGauger) and provides registry modules for Prometheus, Dropwizard, and Spring Boot Actuator integration.

Tokens
7.3K
Snippets
27
Records
41
Agent score
60%

What's inside SOFALookout

  1. Overview of SOFALookout Client

    master
    SOFALookout Client is a Java development library that provides multi-dimensional metrics measurement services for your engineering projects. Unlike traditional hierarchical metrics, it follows the metrics 2.0 standard, allowing for more granular and multi-dimensional data collection.

  2. Overview of SOFALookout

    master

    SOFALookout is a multi-dimensional metrics monitoring and measurement project. It utilizes the Metrics2.0 standard to provide rich monitoring dimensions via tags.

    The project is divided into two main components:

    1. Client: A Java library that can be embedded into your application code to collect metrics.
    2. Server: Handles the collection, processing, storage, and querying of metrics data. It integrates with Grafana for data visualization and uses databases like Elasticsearch (ES) for storage.

    Key advantages include:

    • Multi-dimensional metrics: Adds a set of tags to traditional metric names, providing richer analysis than standard Spring Boot Actuator or Dropwizard.
    • Lightweight: Metrics-based monitoring is more resource-efficient and predictable than log-based monitoring.
    • Broad Support: Supports both the native Java SDK client and industry-standard collection agents (e.g., Metricbeat).
    • Flexible Discovery: Data sources can be located via configuration files or service discovery mechanisms.

  4. Understand configuration priority and isolation in all-in-one-bootstrap

    master

    Because multiple Spring Boot applications run within the same sofa-ark environment, configuration isolation is handled via prefixes. To prevent conflicts (e.g., two apps trying to bind to the same server.port), configuration keys must be prefixed with the application name.

    Configuration Priority

    For a sofa-ark-biz application, the priority (from highest to lowest) is:

    1. [New] Prefixed System Properties (e.g., -Dlookoutgateway.foo=bar)
    2. [New] Prefixed Environment Variables (e.g., lookoutgateway.foo=bar)
    3. System Properties (Standard Spring Boot)
    4. Environment Variables (Standard Spring Boot)
    5. [New] Files in app-configs/<appName> (High priority files provided in the project resources)
    6. Original Classpath Configuration Files (Standard Spring Boot)

    How to pass application-specific configuration

    Using lookoutgateway as an example, you can pass configuration in these ways (ordered by priority):

    1. System Property: -Dlookoutgateway.foo=bar (Affects only lookoutgateway)
    2. Environment Variable: lookoutgateway.foo=bar (Affects only lookoutgateway)
    3. External Properties File: Set -Dlookoutall.config-file=abc.properties. Inside this file, any key starting with lookoutgateway. will apply to that app.
    4. Standard System Properties: (e.g., -Dserver.port=8080 - note this may conflict if not prefixed)
    5. Standard Environment Variables
    6. Additional Location: -Dlookoutgateway.config-additional-location=<dir> (Points to a directory that Spring Boot will parse for lookoutgateway)
    7. Classpath: The application.properties inside the lookoutgateway classpath.

  5. Extend SOFALookout using SPI

    master

    The client provides an SPI (Service Provider Interface) mechanism to allow developers to extend public metrics collection modules. To implement a custom metrics collector, you must implement the com.alipay.lookout.spi.MetricsImporter interface.

    Default extensions provided by the project include:

    • lookout-ext-jvm: JVM metrics
    • lookout-ext-os: OS metrics

  6. Configure metric priority and tags

    master

    Priority Tags

    Priority levels determine the data collection interval. Higher priority metrics are collected more frequently. The default level is NORMAL.

    • LookoutConstants.HIGH_PRIORITY_TAG
    • LookoutConstants.NORMAL_PRIORITY_TAG (Default)
    • LookoutConstants.LOW_PRIORITY_TAG

    Example: id.withTag(LookoutConstants.LOW_PRIORITY_TAG);

    Tag Best Practices

    • Common Tags: Use tags for machine IP, cluster name, or datacenter name. You can customize common tags via the com.alipay.lookout.client.LookoutClient interface. Always include the application name tag (e.g., tag:app=xx).
    • Naming: Tag keys must be lowercase. Use letters, numbers, and underscores.
    • Optimization: Keep the number of tags as small as possible and ensure tag values are enumerable.

  7. Ways to use Lookout Client

    master

    Depending on your project requirements, you can integrate Lookout in three ways:

    1. Standalone Metric Collection: Use lookout-api to manually collect and manage metrics within any Java project.
    2. Prometheus Integration: Add the lookout-reg-prometheus dependency. This starts a nested HTTP server within your project that provides metrics query services, allowing Prometheus to scrape metrics directly.
    3. Spring Boot Integration: Add the lookout-sofa-boot-starter dependency to use the client within a Spring Boot application.

  9. Build the all-in-one-bootstrap project

    master

    To package the project, run the provided build script from the root of the bootstrap directory.

    Note: You must package the project into a JAR file before running it. You cannot run the main method directly in an IDE (like IntelliJ IDEA) because gateway-bootstrap and metrics-server-bootstrap are in the same project. Running via IDE causes IDEA to reference source code directly, which interferes with how sofa-ark modifies the package during runtime.

    ./boot/all-in-one-bootstrap/build.sh

  11. Run the all-in-one-bootstrap executable

    master

    Before running, ensure an Elasticsearch instance is running (e.g., via Docker).

    To run the packaged JAR, use the java -jar command. You must include the system property -Dcom.alipay.sofa.ark.master.biz=lookoutall to set the sofa-ark master biz.

    Required and common flags:

    • -Dcom.alipay.sofa.ark.master.biz=lookoutall: Mandatory for setting the master biz.
    • -Dlookoutall.config-file=<path>: Points to a .properties file on the file system. Configuration keys in this file must be prefixed with the application name to ensure isolation.
    • -D<appName>.<key>=<value>: Sets a configuration value specific to a sub-application.
    • -D<appName>.config-additional-location=<dir>: Specifies a directory for additional configuration files specific to that sub-application.
    # 1. Start Elasticsearch
docker run -d --name es -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" elasticsearch:5.6

# 2. Run the JAR
java -Dcom.alipay.sofa.ark.master.biz=lookoutall \
-Dlookoutgateway.config-additional-location=config-dir-for-lookoutgateway \
-Dlookkoutserver.config-additional-location=config-dir-for-lookoutserver \
-Dlookoutall.config-file=abc.properties \
-Dlookoutgateway.foo=bar \
-Dlookoutserver.bar=baz \
-jar allinone-executable.jar

  12. Import the Lookout API dependency

    master

    To use the Lookout API in your Java project, add the following dependency to your pom.xml. Ensure you define the ${lookout.version} property with the appropriate version.

    <dependency>
	<groupId>com.alipay.lookout</groupId>
	<artifactId>lookout-api</artifactId>
	<version>${lookout.version}</version>
</dependency>