使用 AWS SDK for Java 2.x 操作 Amazon CloudWatch Logs：云端日志监控实战指南

示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载导读本文基于开源仓库 aws-doc-sdk-examples 中 cloudwatch-logs 示例目录 的官方 README 与其完整 Java 源码系统讲解如何通过 AWS SDK for Java 2.x 对接 Amazon CloudWatch Logs实现日志事件的写入、读取、过滤、订阅等核心操作。读完本文你将掌握 CloudWatch Logs 中日志组Log Group、日志流Log Stream、订阅过滤器Subscription Filter三大核心概念对应的 Java API 调用方式并能够直接在本地 Maven 工程中编译、运行这些单操作示例用于排查 EC2、AWS Lambda 或 AWS CloudTrail 等来源产生的应用日志。一、CloudWatch Logs 与 SDK for Java 2.x 概览Amazon CloudWatch Logs 用于对来自 Amazon Elastic Compute CloudEC2实例、AWS CloudTrail 或其他来源的日志文件进行监控、存储和访问。在 SDK for Java 2.x 中对应的服务客户端为CloudWatchLogsClient位于包software.amazon.awssdk.services.cloudwatchlogs它封装了全部日志管理 API包括日志组Log Group日志的逻辑容器通常按应用或服务命名例如/aws/lambda/ChatAIHandler是 Lambda 函数自动创建的日志组。日志流Log Stream日志组内按来源划分的序列每个流内事件按时间排序。订阅过滤器Subscription Filter把符合过滤模式的实时日志事件实时转发到 Lambda、Kinesis 或 Kinesis Data Firehose 等目标。本示例工程所在的 javav2 目录 聚合了 SDK for Java 2.x 的全部代码示例其中 cloudwatch-logs 子项目聚焦上述日志操作目录结构如下javav2/example_code/cloudwatch-logs/ ├── README.md # 官方示例说明本文主体 ├── pom.xml # Maven 构建配置Java 21 AWS SDK BOM 2.35.10 └── src/ ├── main/java/com/example/logs/ # 8 个可运行的 Java 示例类 └── test/java/CloudWatchLogsTest.java # JUnit 5 集成测试二、运行前提与环境准备根据 cloudwatch-logs README 与 javav2 目录 README 的说明运行本示例前需完成具备 AWS 账号与本地凭证按 AWS SDK for Java 开发者指南 配置默认凭证链。示例中部分代码显式使用ProfileCredentialsProvider.create()如DescribeSubscriptionFilters也可依赖默认凭证链。Java 环境工程pom.xml声明java.version、maven.compiler.source与maven.compiler.target均为21请安装 JDK 21 及 Maven 3.6。IAM 最小权限为运行示例的凭证授予 CloudWatch Logs 相关操作的最小权限如logs:GetLogEvents、logs:DescribeLogStreams、logs:PutLogEvents、logs:PutSubscriptionFilter、logs:DeleteSubscriptionFilter等遵循 least privilege 最佳实践。费用提示CloudWatch Logs 的写入、存储、读取均可能产生费用运行示例或测试可能使 AWS 账户产生扣费请留意 AWS Pricing 与 Free Tier 说明代码未在所有 AWS 区域做过测试请以 AWS Regional Services 为准选择区域。三、核心单操作示例逐一解析Single ActionsREADME 将示例归类为“单一操作Single actions”即每次只调用一个服务 API 的代码片段。下面按目录中 8 个类的功能逐一展开5 个为 README 列出项另有 3 个由同目录源码补充。1. GetLogEvents读取日志流中的事件对应文件GetLogEvents.java。该示例演示getLogEventsAPI核心流程分两步第一步用前缀解析出精确日志流名。因为GetLogEventsRequest的logStreamName字段要求精确匹配示例先调用describeLogStreams并传入logStreamNamePrefix如weathertop-java-stream与limit(1)取第一个匹配流的完整名称DescribeLogStreamsRequest describeRequest DescribeLogStreamsRequest.builder() .logGroupName(logGroupName) .logStreamNamePrefix(logStreamPrefix) .limit(1) // get the first matching stream .build(); DescribeLogStreamsResponse describeResponse cloudWatchLogsClient.describeLogStreams(describeRequest); if (describeResponse.logStreams().isEmpty()) { System.out.println(No matching log streams found for prefix: logStreamPrefix); return; } String exactLogStreamName describeResponse.logStreams().get(0).logStreamName();第二步按时间窗口拉取事件。示例用Instant.now()计算最近 7 天的时间窗口毫秒时间戳并设置startFromHead(true)表示从最早事件开始读取long startTime Instant.now().minus(7, ChronoUnit.DAYS).toEpochMilli(); long endTime Instant.now().toEpochMilli(); GetLogEventsRequest getLogEventsRequest GetLogEventsRequest.builder() .logGroupName(logGroupName) .logStreamName(exactLogStreamName) // 精确名称而非前缀 .startTime(startTime) .endTime(endTime) .startFromHead(true) .build(); GetLogEventsResponse response cloudWatchLogsClient.getLogEvents(getLogEventsRequest); response.events().forEach(e - System.out.println(e.message()));参数要点startTime/endTime1970-01-01 00:00:00 UTC 起的毫秒数用于限定事件时间范围startFromHeadtrue表示按时间正序从头读取适合顺序回放日志示例中main方法将日志组、日志流硬编码为WeathertopJavaContainerLogs与weathertop-java-stream测试同名实际使用时应替换为args[0]、args[1]传入。2. CloudWatchLogQuery描述最近更新的日志流DescribeLogStreams对应文件CloudWatchLogQuery.java。演示describeLogStreams的排序与分页能力通过orderBy(OrderBy.LAST_EVENT_TIME)descending(true)limit(1)找出日志组中最近产生事件的日志流并打印其元数据DescribeLogStreamsRequest streamsRequest DescribeLogStreamsRequest.builder() .logGroupName(logGroupName) .orderBy(OrderBy.LAST_EVENT_TIME) .descending(true) .limit(1) .build();返回的LogStream对象可读取以下字段均被示例逐一打印logStreamName()日志流名称arn()日志流 ARNcreationTime()/firstEventTimestamp()/lastEventTimestamp()创建时间、首个与最后事件时间storedBytes()已存储字节数uploadSequenceToken()写入序列令牌见下文 PutLogEvents 中续写日志的关键字段。该类的main默认使用/aws/lambda/ChatAIHandler作为日志组名Lambda 函数自动生成的日志组命名规律展示了典型运维场景查询某个 Lambda 函数最近有没有新日志产生。3. FilterLogEvents按时间窗口过滤日志事件对应文件FilterLogEvents.java。演示filterLogEventsAPI按日志组与时间范围批量检索事件无需先指定日志流FilterLogEventsRequest filterLogEventsRequest FilterLogEventsRequest.builder() .logGroupName(logGroupName) .startTime(startTime) .endTime(endTime) .build(); ListFilteredLogEvent events cloudWatchLogsClient.filterLogEvents(filterLogEventsRequest).events(); for (FilteredLogEvent event : events) { System.out.println(event.message()); }命令行参数为logGroupName startTime endTime其中时间同样以毫秒时间戳表示如1620940080级别的 13 位毫秒值。注意FilterLogEvents也可以进一步通过filterPattern、logStreamNames缩小检索范围——这一组合用法在下面的 CloudWatchLogsSearch 中有所体现。4. CloudWatchLogsSearch搜索日志流并叠加模式过滤对应文件CloudWatchLogsSearch.java。这是 README 中DescribeLogStreams单操作的载体同时也是最实用的组合式检索先按前缀枚举日志组内所有日志流再对每个流应用filterPattern过滤事件并打印DescribeLogStreamsRequest describeLogStreamsRequest DescribeLogStreamsRequest.builder() .logGroupName(logGroupName) .logStreamNamePrefix(logStreamPrefix) .build(); ListLogStream logStreams cwlClient.describeLogStreams(describeLogStreamsRequest).logStreams(); for (LogStream logStream : logStreams) { FilterLogEventsRequest filterLogEventsRequest FilterLogEventsRequest.builder() .logGroupName(logGroupName) .logStreamNames(logStream.logStreamName()) .filterPattern(pattern) .build(); FilterLogEventsResponse response cwlClient.filterLogEvents(filterLogEventsRequest); response.events().forEach(event - System.out.println(event.message())); }运行参数为logGroupName logStreamName pattern例如在WeathertopJavaContainerLogs组内按INFO模式过滤这也是测试类的默认取值。filterPattern支持 CloudWatch Logs 的查询语法如ERROR、?ERROR ?WARN等可用于快速定位指定级别的日志。5. PutLogEvents向日志流写入事件对应文件PutLogEvents.java。演示putLogEvents写入 API。写入前同样先用前缀解析精确流名同时从LogStream取回uploadSequenceToken—— 这是 CloudWatch Logs 保证写序的关键连续写入必须携带上一次写入返回的序列令牌否则会收到InvalidSequenceTokenExceptionString exactStreamName describeLogStreamsResponse.logStreams().get(0).logStreamName(); String sequenceToken describeLogStreamsResponse.logStreams().get(0).uploadSequenceToken(); InputLogEvent inputLogEvent InputLogEvent.builder() .message({ \key1\: \value1\, \key2\: \value2\ }) .timestamp(System.currentTimeMillis()) .build(); PutLogEventsRequest.Builder putLogEventsBuilder PutLogEventsRequest.builder() .logEvents(Collections.singletonList(inputLogEvent)) .logGroupName(logGroupName) .logStreamName(exactStreamName); // 仅当令牌存在时才设置否则跳过 if (sequenceToken ! null) { putLogEventsBuilder.sequenceToken(sequenceToken); } logsClient.putLogEvents(putLogEventsBuilder.build());要点InputLogEvent.timestamp()需为毫秒时间戳且事件时间不得早于日志流的保留窗口新日志流首次写入时无序列令牌示例通过if (sequenceToken ! null)优雅处理了这两种情况示例消息使用 JSON 字符串便于后续配合 CloudWatch Logs 结构化检索。6. PutSubscriptionFilter创建订阅过滤器转发到 Lambda对应文件PutSubscriptionFilter.java。演示putSubscriptionFilterAPI将日志组中匹配模式的实时事件转发到 Lambda 函数PutSubscriptionFilterRequest request PutSubscriptionFilterRequest.builder() .filterName(filter) // 过滤器名称如 myfilter .filterPattern(pattern) // 过滤模式如 ERROR .logGroupName(logGroup) // 日志组名如 testgroup .destinationArn(functionArn) // 目标 Lambda 函数 ARN .build(); cwl.putSubscriptionFilter(request);该类的类注释中给出了必须先执行的 AWS CLI 授权命令——要让 CloudWatch Logs 具备调用你 Lambda 函数的权限需要在创建过滤器前执行aws lambda add-permission --function-name lamda1 --statement-id lamda1 \ --principal logs.us-west-2.amazonaws.com \ --action lambda:InvokeFunction \ --source-arn arn:aws:logs:us-west-2:111111111111:log-group:testgroup:* \ --source-account 111111111111务必把函数名lamda1、账户111111111111替换为实际值且日志组所在区域示例为us-west-2需与--principal中的区域一致。具体可参考 Amazon CloudWatch Logs 用户指南中 Subscription Filters with AWS Lambda 一节。7. DescribeSubscriptionFilters分页列举订阅过滤器对应文件DescribeSubscriptionFilters.java。演示describeSubscriptionFiltersAPI并展示了 AWS SDK for Java 2.x 中经典的nextToken手动分页模式每页limit(1)当响应nextToken()为 null 时结束循环boolean done false; String newToken null; while (!done) { DescribeSubscriptionFiltersResponse response; if (newToken null) { DescribeSubscriptionFiltersRequest request DescribeSubscriptionFiltersRequest.builder() .logGroupName(logGroup) .limit(1).build(); response logs.describeSubscriptionFilters(request); } else { DescribeSubscriptionFiltersRequest request DescribeSubscriptionFiltersRequest.builder() .nextToken(newToken) .logGroupName(logGroup) .limit(1).build(); response logs.describeSubscriptionFilters(request); } for (SubscriptionFilter filter : response.subscriptionFilters()) { System.out.printf(Retrieved filter with name %s, pattern %s and destination arn %s, filter.filterName(), filter.filterPattern(), filter.destinationArn()); } if (response.nextToken() null) { done true; } else { newToken response.nextToken(); } }SubscriptionFilter对象携带filterName、filterPattern、destinationArn三个关键属性可用于审计当前日志组已配置的转发规则。该类的客户端通过ProfileCredentialsProvider.create()显式指定凭证来源。8. DeleteSubscriptionFilter删除订阅过滤器对应文件DeleteSubscriptionFilter.java。与创建形成闭环演示deleteSubscriptionFilterAPI命令参数为filter logGroupDeleteSubscriptionFilterRequest request DeleteSubscriptionFilterRequest.builder() .filterName(filter) // 要删除的过滤器名称 .logGroupName(logGroup) // 所属日志组 .build(); logs.deleteSubscriptionFilter(request); System.out.printf(Successfully deleted CloudWatch logs subscription filter %s, filter);四、Maven 依赖与工程配置本工程通过 pom.xml 统一管理依赖是理解示例运行环境的关键Java 版本java.version/maven.compiler.source/maven.compiler.target均为21AWS SDK 版本统一通过dependencyManagement引入software.amazon.awssdk:bom:2.35.10Bill of Materialscloudwatchlogs与cloudwatch两个核心依赖均不写版本号由 BOM 统一锁定避免版本冲突测试框架junit-jupiter5.11.4配合maven-surefire-plugin3.5.2 执行辅助依赖jackson-core/jackson-databind与gson用于 JSON 处理log4j-corelog4j-slf4j2-implslf4j-api提供日志输出netty-nio-client为 HTTP 异步客户端sso/ssooidc支持 AWS IAM Identity CenterSSO凭证流程secretsmanager用于测试凭证管理。在 javav2 目录 完成环境准备后可在本目录执行# 编译 mvn compile # 运行某个示例例如读取日志事件 mvn exec:java -Dexec.mainClasscom.example.logs.GetLogEvents # 或先 package 再以 java -cp 运行 mvn package五、集成测试与验证工程配套 CloudWatchLogsTest.java是基于 JUnit 5 的集成测试全部用例带有Tag(IntegrationTest)标记并可通过Order控制执行顺序序号测试方法覆盖的类与方法1testSearchLogStreamsCloudWatchLogsSearch.searchLogStreamsAndFilterEvents2testDescribeMostRecentCloudWatchLogQuery.describeMostRecentLogStream3testDescribeSubscriptionFiltersDescribeSubscriptionFilters.describeFilters4testterFilterLogEventsFilterLogEvents.filterCWLogEvents最近 7 天窗口5testGetCWLogEventsGetLogEvents.getCWLogEvents6testputCWLogEventsPutLogEvents.putCWLogEvents测试在BeforeAll中创建指向Region.US_EAST_1的CloudWatchLogsClient并使用占位值WeathertopJavaContainerLogs日志组、weathertop-java-stream日志流、INFO过滤模式。运行测试前必须把这三个常量替换为你账号下真实存在的日志组与日志流。执行方式mvn test运行测试将对真实 AWS 资源发起请求可能产生 AWS 账户费用且测试前需要确保目标日志组与日志流已存在PutLogEvents 不会自动创建日志组/日志流。六、从源码看客户端构造的两种方式对比 8 个示例的客户端创建代码可归纳出 SDK for Java 2.x 的两种常用构造方式均基于 Builder 模式默认凭证链 显式区域多数示例采用例如GetLogEventsCloudWatchLogsClient cloudWatchLogsClient CloudWatchLogsClient.builder() .region(Region.US_EAST_1) .build();显式凭证提供器例如DescribeSubscriptionFilters使用ProfileCredentialsProvider.create()从本地~/.aws/credentials配置文件中读取命名配置文件。需要注意Region.US_EAST_1与Region.US_WEST_2在示例间并不统一PutSubscriptionFilter、FilterLogEvents使用US_WEST_2实际部署时请与日志组所在的区域保持一致否则会收到资源不存在或区域不匹配的错误。所有示例在main方法末尾调用client.close()释放底层 HTTP 连接资源这是 SDK for Java 2.x 的标准实践。七、进一步学习深入阅读本目录全部源码src/main/java/com/example/logs掌握 javav2 全部示例的通用前提与测试说明javav2 READMECloudWatch Logs 概念与日志查询语法CloudWatch Logs 用户指南与 API ReferenceSDK for Java 2.x 的 CloudWatch Logs 客户端 API 参考AWS SDK for Java API Reference 中software.amazon.awssdk.services.cloudwatchlogs包本文内容基于当前仓库 cloudwatch-logs README 及其源码整理。示例代码版权归 Amazon.com, Inc. 或其关联公司所有采用 Apache-2.0 许可证。赞分享示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载相关推荐AWS SDK for Java 2.x 操作 Amazon S3 完全指南AWS SDK for Java 2.x 操作 Amazon S3 完全指南 概述 Amazon Simple Storage Service Amazon S示例工程教程后端使用 AWS SDK for .NET 操作 CloudWatch Logs8 个单操作示例实战指南使用 AWS SDK for .NET 操作 CloudWatch Logs8 个单操作示例实战指南 导读 本文以 dotnetv3/CloudWatchLo示例工程教程后端aws-doc-sdk-examples 中的 Amazon CloudWatch Java SDK 2.x 实战指南从 Hello CloudWatch 到 PromQL 告警aws doc sdk examples 中的 Amazon CloudWatch Java SDK 2.x 实战指南从 Hello CloudWatch 到示例工程教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考