首页日志服务操作指南查询与分析最佳实践通过PackId机制关联日志上下文
输入文档关键字查找

通过PackId机制关联日志上下文

更新时间：2025-03-28 03:21
产品详情
社区

日志上下文查询用于指定日志来源（例如，特定的机器和文件），并查找该来源中某条日志的前后若干条日志，以获取其上下文信息。在处理大量日志时，可通过为日志添加标识符 PackId 将相关日志进行分组。使用 PackId 可以快速且完整地查询相关日志组，从而高效定位日志的上下文。本文介绍如何为日志添加PackId。

工作原理

服务端利用PackId机制关联日志上下文，PackId格式为上下文前缀-日志组ID，例如 5FA51423DDB54FDA-1E3。说明如下：

  • 上下文前缀：由大写的十六进制数字组成。例如 5FA51423DDB54FDA。相同上下文前缀表示属于同一日志上下文。

  • 日志组ID：由大写的十六进制数字组成。例如 1E3。在同一日志上下文内，日志组ID 是递增的，例如 1E3 与 1E4属于同一日志上下文的相邻日志组。

PackId是由客户端生成的，并在日志写入请求时一同发送到服务端。具有相同上下文前缀的日志被认为属于同一日志上下文。

自动生成PackId

  • 使用Producer SDK写入的日志：由同一Producer对象实例发送的日志数据属于同一上下文，可以直接用于上下文查询。例如，当使用Aliyun Log Java Producer写入日志数据或C SDK写入日志时，系统会自动生成并携带PackId作为上下文标识。

  • 通过Logtail采集的日志：使用Logtail采集的日志会自动生成并携带PackId，同一采集对象（如主机、pod等）上的同一日志文件属于同一上下文，可以直接用于上下文查询。

手动生成PackId并通过PutLogs接口上传

参数说明

PutLogs - 写入日志接口用于将日志写入日志服务。在手动生成PackId后，需将该PackId放置在PutLogs请求中的LogGroup的LogTags属性里，其中Key设定为__pack_id__，参数示例如下：

{
  "Topic": "my-topic",
  "Source": "127.0.0.1",
  "LogTags": [
      {
        "Key": "__pack_id__",
        "Value": "5FA51423DDB54FDA-1"
      },
      {
        "Key": "my_other_tag_key",
        "Value": "my_other_tag_value"
      }
   ],
   "Logs": [
     {
       "Time": 1728961415,
        "Contents": [
            {
              "Key": "hello",
              "Value": "world"
            }
        ]
     }
   ]
}

示例代码

Java示例
Go示例

  1. 在pom.xml文件中添加如下依赖。

     <dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>27.0.1-jre</version>
</dependency>
<dependency>
    <groupId>com.aliyun.openservices</groupId>
    <artifactId>aliyun-log</artifactId>
    <version>0.6.111</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.12</version>
</dependency>

  2. 使用如下代码，手动生成PackId并通过PutLogs接口上传。根据实际情况替换参数project、logstore、endpoint、accessKeyId和accessKeySecret。

    package org.example;

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.LogItem;
import com.aliyun.openservices.log.common.TagContent;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.request.PutLogsRequest;
import com.google.common.base.Charsets;
import com.google.common.hash.Hashing;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.lang.management.ManagementFactory;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.net.SocketException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Enumeration;
import java.util.List;
import java.util.concurrent.atomic.AtomicLong;

public class Main {
    private static final String TAG_PACK_ID = "__pack_id__";
    private static final int TOKEN_LEN = 4;

    public static void main(String[] args) throws LogException {
        System.out.println("Hello world!");
        // 同一个上下文只需要使用同一个 PackIdGenerator 就可以了
        PackIdGenerator generator1 = new PackIdGenerator();
        System.out.println(generator1.generateNewPackId());
        System.out.println(generator1.generateNewPackId());
        System.out.println(generator1.generateNewPackId());
        // 不同的上下文用不同的 PackIdGenerator
        PackIdGenerator generator2 = new PackIdGenerator();
        System.out.println(generator2.generateNewPackId());
        System.out.println(generator2.generateNewPackId());

        // 与日志相配合
        String project = "project";
        String logstore = "logstore";
        String topic = "topic";
        String source = "127.0.0.1";
        Client client = new Client("endpoint", "accessKeyId", "accessKeySecret");
        List<LogItem> logs = new ArrayList<>();
        LogItem log = new LogItem();
        log.PushBack("hello", "world");
        logs.add(log);

        // 发送日志请求
        PutLogsRequest req = new PutLogsRequest(project, logstore, topic, source, logs);
        // 把 pack id 放在 tag 列表里
        req.SetTags(Arrays.asList(new TagContent(TAG_PACK_ID, generator1.generateNewPackId())));
        client.PutLogs(req);

        // 发送日志请求
        PutLogsRequest req2 = new PutLogsRequest(project, logstore, topic, source, logs);
        req.SetTags(Arrays.asList(new TagContent(TAG_PACK_ID, generator1.generateNewPackId())));
        client.PutLogs(req2);
    }

    public static class NetworkUtils {
        private NetworkUtils() {
        }

        public static boolean isIpAddress(final String ipAddress) {
            if (ipAddress == null || ipAddress.isEmpty()) {
                return false;
            }
            try {
                final String[] tokens = ipAddress.split("\\.");
                if (tokens.length != TOKEN_LEN) {
                    return false;
                }
                for (String token : tokens) {
                    int i = Integer.parseInt(token);
                    if (i < 0 || i > 255) {
                        return false;
                    }
                }
                return true;
            } catch (Exception ex) {
                return false;
            }
        }

        public static String getLocalMachineIp() {
            try {
                Enumeration<NetworkInterface> networkInterfaces = NetworkInterface.getNetworkInterfaces();
                while (networkInterfaces.hasMoreElements()) {
                    NetworkInterface ni = networkInterfaces.nextElement();
                    if (!ni.isUp()) {
                        continue;
                    }
                    Enumeration<InetAddress> addresses = ni.getInetAddresses();
                    while (addresses.hasMoreElements()) {
                        final InetAddress address = addresses.nextElement();
                        if (!address.isLinkLocalAddress() && address.getHostAddress() != null) {
                            String ipAddress = address.getHostAddress();
                            if ("127.0.0.1".equals(ipAddress)) {
                                continue;
                            }
                            if (isIpAddress(ipAddress)) {
                                return ipAddress;
                            }
                        }
                    }
                }
            } catch (SocketException ex) {
                // swallow it
            }
            return null;
        }
    }

    public static class PackIdGenerator {
        private static final Logger LOGGER = LoggerFactory.getLogger(PackIdGenerator.class);
        private static final AtomicLong GENERATORID = new AtomicLong(0);
        private final String packIdPrefix;
        private final AtomicLong batchId = new AtomicLong(0);

        public PackIdGenerator() {
            packIdPrefix = generatePackIdPrefix(GENERATORID.getAndIncrement()).toUpperCase() + "-";
        }

        public String generateNewPackId() {
            return packIdPrefix + Long.toHexString(batchId.getAndIncrement()).toUpperCase();
        }

        private String generatePackIdPrefix(Long instanceId) {
            String ip = NetworkUtils.getLocalMachineIp();
            if (ip == null) {
                LOGGER.warn("Failed to get local machine ip, set ip to 127.0.0.1");
                ip = "127.0.0.1";
            }
            String name = ManagementFactory.getRuntimeMXBean().getName();
            String input = ip + "-" + name + "-" + instanceId;
            return Hashing.farmHashFingerprint64().hashString(input, Charsets.US_ASCII).toString();
        }
    }

}

    示例代码中的参数说明

    参数名

    参数含义

    示例值

    project

    日志服务的Project名。

    test-project

    logstore

    日志服务的Logstore名。

    test-logstore

    endpoint

    日志服务的公网域名，获取方式请参见服务接入点。

    cn-hangzhou.log.aliyuncs.com

    accessKeyId

    用户身份识别ID，获取方式，请参见创建AccessKey。

    yourAccessKeyID

    accessKeySecret

    用于验证您拥有该AccessKey ID的密码。获取方式，请参见创建AccessKey。

    yourAccessKeySecret

  1. 在命令行执行如下命令，安装Go SDK和protobuf依赖包。

    go get -u github.com/aliyun/aliyun-log-go-sdk
go get google.golang.org/protobuf

  2. 使用如下代码，手动生成PackId并通过PutLogs接口上传。根据实际情况替换参数project、logstore、endpoint、accessKeyId和accessKeySecret。

    package main

import (
	"crypto/md5"
	"fmt"
	"os"
	"sync/atomic"
	"time"

	sls "github.com/aliyun/aliyun-log-go-sdk"
	"google.golang.org/protobuf/proto"
)

func main() {
	// 同一个上下文只需要使用同一个 PackIdGenerator 就可以了
	g1 := NewPackIdGenerator()
	fmt.Println(g1.Generate())
	fmt.Println(g1.Generate())
	fmt.Println(g1.Generate())
	// 不同的上下文用不同的 PackIdGenerator
	g2 := NewPackIdGenerator()
	fmt.Println(g2.Generate())
	fmt.Println(g2.Generate())

	// 与日志相配合
	project := "project"
	logstore := "logStore"
	topic := "topic"
	source := "source"

	client := sls.CreateNormalInterface("endpoint", "accessKeyId", "accessKeySecret", "")

	logs := []*sls.Log{
		{
			Time: proto.Uint32(uint32(time.Now().Unix())),
			Contents: []*sls.LogContent{
				{
					Key:   proto.String("hello"),
					Value: proto.String("world"),
				},
				{
					Key:   proto.String("hi"),
					Value: proto.String("world"),
				},
			},
		},
	}
	// 使用 PostLogStoreLogsV2 接口写入日志
	err := client.PostLogStoreLogsV2(project, logstore, &sls.PostLogStoreLogsRequest{
		LogGroup: &sls.LogGroup{
			Topic:  &topic,
			Source: &source,
			Logs:   logs,
			LogTags: []*sls.LogTag{
				{
					Key:   proto.String("__pack_id__"), // pack id 加到 tag 列表里
					Value: proto.String(g1.Generate()),
				},
			},
		},
	})
	if err != nil {
		panic(err)
	}

	// 使用 PutLogs 接口写入日志， g1.Generate() 重新生成一个新的 packid
	err = client.PutLogs(project, logstore, &sls.LogGroup{
		Topic:  &topic,
		Source: &source,
		Logs:   logs,
		LogTags: []*sls.LogTag{
			{
				Key:   proto.String("__pack_id__"), // pack id 加到 tag 列表里
				Value: proto.String(g1.Generate()),
			},
		},
	})
	if err != nil {
		panic(err)
	}

}

type PackIdGenerator struct {
	prefix string
	id     atomic.Uint64
}

func NewPackIdGenerator() *PackIdGenerator {
	return &PackIdGenerator{
		prefix: generatePackIDPrefix(),
		id:     atomic.Uint64{},
	}
}

func (g *PackIdGenerator) Generate() string {
	return fmt.Sprintf("%s-%X", g.prefix, g.id.Add(1))
}

// make context by (hostname, pid, time)
func generatePackIDPrefix() string {
	m := md5.New()
	m.Write([]byte(time.Now().String()))
	hostName, _ := os.Hostname()
	m.Write([]byte(hostName))
	m.Write([]byte(fmt.Sprintf("%v", os.Getpid())))
	return fmt.Sprintf("%X", m.Sum(nil))
}

    示例代码中的参数说明

    参数名

    参数含义

    示例值

    project

    日志服务的Project名。

    test-project

    logstore

    日志服务的Logstore名。

    test-logstore

    endpoint

    日志服务的公网域名，获取方式请参见服务接入点。

    cn-hangzhou.log.aliyuncs.com

    accessKeyId

    用户身份识别ID，获取方式，请参见创建AccessKey。

    yourAccessKeyID

    accessKeySecret

    用于验证您拥有该AccessKey ID的密码。获取方式，请参见创建AccessKey。

    yourAccessKeySecret

查看日志上下文信息

  1. 在目标Project页面，单击目标Logstore，参考下图，在原始日志 > 原始页签下，找到目标日志，单击查询日志-004图标。

    说明

    每次通过PutLogs - 写入日志提交的日志中，具有相同PackId上下文前缀的日志被视为属于同一日志上下文。日志服务内部已根据PackId进行分类，单击上下文浏览功能即可查看指定日志的上下文信息，即显示具有同一上下文前缀的不同日志组，其中高亮代表目标日志。

    image

  2. 使用鼠标在当前页面上下滚动查看指定日志的上下文信息。

    image

相关文档

上一篇：时间字段转换示例下一篇：通过Scan搜索实现上下文查询
  • 本页导读 （1）
  • 工作原理
  • 自动生成PackId
  • 手动生成PackId并通过PutLogs接口上传
  • 参数说明
  • 示例代码
  • 查看日志上下文信息
  • 相关文档
文档反馈