Use Simple Log Service SDK for Java to manage machine groups - Simple Log Service

A machine group is a virtual group of multiple servers. Simple Log Service uses machine groups to manage the servers whose logs are collected by using Logtail. This topic describes how to create, modify, query, and delete a machine group by using Simple Log Service SDK for Java and provides sample code.

Prerequisites

A Resource Access Management (RAM) user is created, and the required permissions are granted to the RAM user. For more information, see Create a RAM user and grant permissions to the RAM user.
The ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured. For more information, see Configure environment variables in Linux, macOS, and Windows.
Important
- The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use the AccessKey pair of a RAM user to call API operations or perform routine O&M.
- We recommend that you do not save the AccessKey ID or AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked, and the security of all resources within your account may be compromised.
Simple Log Service SDK for Java is installed. For more information, see Install Simple Log Service SDK for Java.
A project is created. For more information, see Use Simple Log Service SDK for Java to manage projects.

Usage notes

In this example, the public Simple Log Service endpoint for the China (Hangzhou) region is used, which is https://cn-hangzhou.log.aliyuncs.com. If you want to access Simple Log Service by using other Alibaba Cloud services that reside in the same region as your project, you can use the internal Simple Log Service endpoint, which is https://cn-hangzhou-intranet.log.aliyuncs.com. For more information about the supported regions and endpoints of Simple Log Service, see Endpoints.

Sample code that is used to create a machine group

The following sample code provides an example on how to create a machine group named ali-test-machinegroup:

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.GroupAttribute;
import com.aliyun.openservices.log.common.MachineGroup;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.request.CreateMachineGroupRequest;

import java.util.Collections;

public class CreateMachineGroup {
    public static void main(String[] args) throws LogException {
        // In this example, the AccessKey ID and AccessKey secret are obtained from environment variables. 
        String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // The name of the project. 
        String projectName = "ali-test-project";
        // The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint. 
        String host = "https://cn-hangzhou.log.aliyuncs.com";

        // Create a Simple Log Service client. 
        Client client = new Client(host, accessId, accessKey);

        try {
            // The name of the machine group 
            String machineGroupName = "ali-test-machinegroup";
            System.out.println("ready to create machinegroup");

            MachineGroup machineGroup = new MachineGroup();
           
            machineGroup.SetGroupName(machineGroupName);

            // Specify the identifier type of the machine group. In this example, create an IP address-based machine group. 
            machineGroup.SetMachineIdentifyType("ip");

            // Specify the attribute of the machine group. 
            GroupAttribute groupAttribute = new GroupAttribute();

            // Specify the topic of the machine group. 
            groupAttribute.SetGroupTopic("ide test");
            machineGroup.SetGroupAttribute(groupAttribute);

            // Specify the identifier of the machine group. In this example, enter an IP address. 
            machineGroup.SetMachineList(Collections.singletonList("192.168.XX.XX"));

            // Create the machine group. 
            CreateMachineGroupRequest request = new CreateMachineGroupRequest(projectName, machineGroup);
            client.CreateMachineGroup(request);

            System.out.println(String.format("create machinegroup %s success", machineGroupName));

        } catch (LogException e) {
            System.out.println("LogException e :" + e.toString());
            System.out.println("error code :" + e.GetErrorCode());
            System.out.println("error message :" + e.GetErrorMessage());
            throw e;
        }
    }
}

Expected result:

ready to create machinegroup
create machinegroup ali-test-machinegroup success

Sample code that is used to modify a machine group

The following sample code provides an example on how to modify a machine group named ali-test-machinegroup:

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.GroupAttribute;
import com.aliyun.openservices.log.common.MachineGroup;
import com.aliyun.openservices.log.exception.LogException;

import java.util.Collections;

public class UpdateMachineGroup {
    public static void main(String[] args) throws LogException {
        // In this example, the AccessKey ID and AccessKey secret are obtained from environment variables. 
        String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // The name of the project. 
        String projectName = "ali-test-project";
        // The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint. 
        String host = "https://cn-hangzhou.log.aliyuncs.com";

        // Create a Simple Log Service client. 
        Client client = new Client(host, accessId, accessKey);

        try {
            // The name of the machine group. 
            String machineGroupName = "ali-test-machinegroup";
            System.out.println("ready to update machinegroup");

            MachineGroup machineGroup = new MachineGroup();
            
            machineGroup.SetGroupName(machineGroupName);

            // Specify the identifier type of the machine group. In this example, create an IP address-based machine group. 
            machineGroup.SetMachineIdentifyType("ip");

            // Specify the attribute of the machine group. 
            GroupAttribute groupAttribute = new GroupAttribute();

            // Specify the topic of the machine group. 
            groupAttribute.SetGroupTopic("new ide test");
            machineGroup.SetGroupAttribute(groupAttribute);

            // Update the machine group. 
            client.UpdateMachineGroup(projectName, machineGroup);

            System.out.println(String.format("update machinegroup %s success", machineGroupName));

        } catch (LogException e) {
            System.out.println("LogException e :" + e.toString());
            System.out.println("error code :" + e.GetErrorCode());
            System.out.println("error message :" + e.GetErrorMessage());
            throw e;
        }
    }
}

Expected result:

ready to update logstore
update logstore ali-test-logstore success

Sample code that is used to query all machine groups

The following sample code provides an example on how to query all machine groups in a specified project:

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.response.ListMachineGroupResponse;

public class ListMachineGroup {
    public static void main(String[] args) throws LogException {
        // In this example, the AccessKey ID and AccessKey secret are obtained from environment variables. 
        String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // The name of the project. 
        String projectName = "ali-test-project";
        // The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint. 
        String host = "https://cn-hangzhou.log.aliyuncs.com";

        // Create a Simple Log Service client. 
        Client client = new Client(host, accessId, accessKey);

        try {
            System.out.println("ready to list machinegroup");

            // Query all machine groups in the project. 
            ListMachineGroupResponse response = client.ListMachineGroup(projectName);

            for (String machineGroup : response.GetMachineGroups()) {
                System.out.println(machineGroup.toString());
            }

            System.out.println(String.format("list project %s machinegroup success", projectName));

        } catch (LogException e) {
            System.out.println("LogException e :" + e.toString());
            System.out.println("error code :" + e.GetErrorCode());
            System.out.println("error message :" + e.GetErrorMessage());
            throw e;
        }
    }
}

Expected result:

ready to list machinegroup
ali-test-machinegroup
ali-test-machinegroup2
list project ali-test-project machinegroup success

Sample code that is used to query a specified machine group

The following sample code provides an example on how to query a specified machine group:

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.MachineGroup;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.response.GetMachineGroupResponse;

public class GetMachineGroup {
    public static void main(String[] args) throws LogException {
        // In this example, the AccessKey ID and AccessKey secret are obtained from environment variables. 
        String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // The name of the project. 
        String projectName = "ali-test-project";
        // The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint. 
        String host = "https://cn-hangzhou.log.aliyuncs.com";

        // Create a Simple Log Service client. 
        Client client = new Client(host, accessId, accessKey);

        try {
            // The name of the machine group. 
            String machineGroupName = "ali-test-machinegroup";
            System.out.println("ready to get machinegroup");

            // Query the machine group. 
            GetMachineGroupResponse response = client.GetMachineGroup(projectName, machineGroupName);
            MachineGroup machineGroup = response.GetMachineGroup();

            // Display the information about the machine group. 
            System.out.println("The machinegroup name is:" + machineGroup.GetGroupName());
            System.out.println("The machinegroup topic is:" + machineGroup.GetGroupTopic());
            System.out.println("The machinegroup list is:" + machineGroup.GetMachineList());

            System.out.println(String.format("get machinegroup from %s success", projectName));

        } catch (LogException e) {
            System.out.println("LogException e :" + e.toString());
            System.out.println("error code :" + e.GetErrorCode());
            System.out.println("error message :" + e.GetErrorMessage());
            throw e;
        }
    }
}

Expected result:

ready to get machinegroup
The machinegroup name is:ali-test-machinegroup
The machinegroup topic is:new ide test
The machinegroup list is:[192.168.XX.XX]
get machinegroup from ali-test-project success

Sample code that is used to delete a machine group

The following sample code provides an example on how to delete a machine group in a specified project:

Important

After a machine group is deleted, the Logtail configuration of the machine group is no longer applied to the machine group, and logs cannot be collected.

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.exception.LogException;

public class DeleteMachineGroup {
    public static void main(String[] args) throws LogException {
        // In this example, the AccessKey ID and AccessKey secret are obtained from environment variables. 
        String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // The name of the project. 
        String projectName = "ali-test-project";
        // The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint. 
        String host = "https://cn-hangzhou.log.aliyuncs.com";

        // Create a Simple Log Service client. 
        Client client = new Client(host, accessId, accessKey);

        try {
            // The name of the machine group. 
            String machineGroupName = "ali-test-machinegroup";
            System.out.println("ready to delete machinegroup");

            // Delete the machine group. 
            client.DeleteMachineGroup(projectName, machineGroupName);

            System.out.println(String.format("delete machinegroup from %s success", projectName));

        } catch (LogException e) {
            System.out.println("LogException e :" + e.toString());
            System.out.println("error code :" + e.GetErrorCode());
            System.out.println("error message :" + e.GetErrorMessage());
            throw e;
        }
    }
}

Expected result:

ready to delete machinegroup
delete machinegroup from ali-test-project success

References

If the response that is returned by Log Service contains error information after you call an API operation, the call fails. You can handle errors based on the error codes that are returned when API calls fail. For more information, see Error codes.
Alibaba Cloud OpenAPI Explorer provides debugging capabilities, SDKs, examples, and related documents. You can use OpenAPI Explorer to debug Log Service API operations without the need to manually encapsulate or sign requests. For more information, visit OpenAPI Portal.
Log Service provides the command-line interface (CLI) to meet the requirements for automated configurations in Log Service. For more information, see Log Service CLI.
For more information about machine group-related operations, see the following topics:
For more information about sample code, see Alibaba Cloud Log Service SDK for Java on GitHub.