SkyWalking
· 阅读需 24 分钟
一、项目概述
Apache SkyWalking 是一款专为微服务、云原生及容器化架构设计的开源可观测性平台，提供分布式追踪、服务网格遥测分析、度量聚合与可视化的一体化解决方案。在传统单体应用向分布式架构演进的过程中，系统复杂度呈指数级增长，传统的日志监控与指标监控已无法满足故障定位与性能诊断的需求。SkyWalking 的核心价值在于填补了这一技术空白，通过全链路追踪能力，将原本黑盒化的跨服务调用过程转化为可视化的调用链，使开发运维人员能够快速定位性能瓶颈与故障根因。
与传统APM工具相比，SkyWalking 具备三大差异化优势：第一，无侵入式探针设计，通过字节码增强技术实现监控数据采集，无需修改业务代码；第二，高性能通信架构，采用gRPC协议进行数据传输，大幅降低监控开销；第三，跨语言生态支持，覆盖Java、.NET Core、PHP、Node.js、Go、Python等主流编程语言，完美适配异构技术栈的微服务体系。
主要功能特性
SkyWalking 的功能矩阵围绕可观测性的三大支柱（指标、日志、追踪）构建：
- 分布式追踪：自动采集服务间调用链路，生成端到端的Trace记录，支持跨进程、跨语言的调用关系还原。每个Trace包含完整的Span层级结构，可精确到方法级别的耗时分析。
- 服务拓扑发现：基于调用关系数据自动绘 制服务依赖图谱，直观展示微服务间的调用流向与依赖强度，识别关键路径与单点故障风险。
- 应用性能指标监控：采集JVM内存、CPU使用率、GC频率、线程状态等运行时指标，提供多维度的性能基线分析与异常检测。
- 告警与通知：支持基于阈值、同比环比、异常检测等多种规则的告警配置，可通过Webhook、邮件、钉钉、企业微信等渠道实时通知。
- 日志关联分析：将业务日志与Trace ID自动关联，实现日志上下文与调用链路的双向跳转，加速故障排查过程。
- 服务网格集成：原生支持Envoy + Istio构建的Service Mesh架构，可监控服务网格内的流量路由、负载均衡与安全策略执行情况。
适用场景
SkyWalking 的适用场景覆盖从开发测试到生产运维的全生命周期：
- 微服务性能诊断：当接口响应时间异常时，通过调用链分析快速定位慢查询服务、数据库瓶颈或第三方API延迟。
- 容量规划与优化：基于历史性能数据识别服务资源瓶颈，为弹性伸缩与资源分配提供数据支撑。
- 故障根因定位：结合链路、指标与日志三要素，在服务异常时迅速缩小排查范围，确定故障发生的具体服务与方法。
- 架构演进验证：在服务拆分、技术栈迁移等架构变更后，验证新架构的性能表现与稳定性。
- SLA合规监控：监控关键业务接口的可用性与响应时间，确保服务等级协 议（SLA）的持续达标。
二、SkyWalking架构详解
四大核心组件
SkyWalking 采用四层架构设计：探针（Agent） 部署于应用实例，负责无侵入采集追踪数据；后端服务（OAP Server） 接收、聚合、分析数据；存储（Storage） 持久化处理结果至Elasticsearch、MySQL等数据库；UI界面 提供可视化展示与查询功能。
数据流转机制
探针通过HTTP/gRPC将Trace Segment协议数据发送至OAP Server，OAP进行流式分析后写入存储层，UI从存储读取数据生成拓扑图与性能仪表盘。跨语言调用通过标准化Sw8 Header传递上下文，确保异构服务链路完整拼接。
三、本地部署方法详解
环境准备与依赖检查
在开始部署 SkyWalking 之前，请确保您的系统满足以下最低要求：
操作系统：Linux（CentOS 7+/Ubuntu 18.04+）、macOS 10.14+、Windows 10（WSL2推荐）
内存：至少 4GB RAM（生产环境建议 8GB+）
磁盘空间：至少 10GB 可用空间
核心依赖版本：
- Java 8 或更高版本（推荐 OpenJDK 11）
- MySQL 5.7+ 或 Elasticsearch 7.x（用于数据存储）
- 网络端口：11800（gRPC）、12800（HTTP）、8080（UI，可自定义）
可在此处配一张终端检查Java版本的截图，显示 java -version 命令输出
快速验证命令：
# 检查Java版本
java -version
# 检查MySQL状态（如使用MySQL存储）
systemctl status mysql
# 检查端口占用情况
netstat -tlnp | grep -E '11800|12800|8080'
手动部署步骤
1. 下载与解压
从 Apache SkyWalking 官网下载最新版本（当前稳定版为 9.7.0）：
# 下载压缩包
wget https://dlcdn.apache.org/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz
# 解压到指定目录
tar -zxvf apache-skywalking-apm-9.7.0.tar.gz -C /opt/
cd /opt/apache-skywalking-apm-9.7.0
解压后的目录结构：
bin/：启动脚本（oapService.sh、webappService.sh）config/：配置文件目录agent/：Java Agent 探针webapp/：UI 前端资源
2. MySQL存储配置详解
SkyWalking 默认使用 H2 内存数据库，适合测试环境。生产环境推荐使用 MySQL 或 Elasticsearch。以下以 MySQL 为例：
步骤一：创建数据库与用户
-- 登录MySQL
mysql -u root -p
-- 创建数据库（字符集必须为utf8）
CREATE DATABASE IF NOT EXISTS `skywalking`
DEFAULT CHARACTER SET utf8
DEFAULT COLLATE utf8_general_ci;
-- 创建专用用户
CREATE USER 'skywalking'@'%' IDENTIFIED BY 'YourPassword123!';
GRANT ALL PRIVILEGES ON skywalking.* TO 'skywalking'@'%';
FLUSH PRIVILEGES;
步骤二：修改 OAP 配置文件编辑 config/application.yml，找到 storage 配置段：
storage:
selector: ${SW_STORAGE:mysql} # 指定使用MySQL
mysql:
properties:
jdbcUrl: ${SW_JDBC_URL:"jdbc:mysql://localhost:3306/skywalking?rewriteBatchedStatements=true"}
dataSource.user: ${SW_DATA_SOURCE_USER:skywalking}
dataSource.password: ${SW_DATA_SOURCE_PASSWORD:YourPassword123!}
dataSource.cachePrepStmts: ${SW_DATA_SOURCE_CACHE_PREP_STMTS:true}
dataSource.prepStmtCacheSize: ${SW_DATA_SOURCE_PREP_STMT_CACHE_SIZE:250}
dataSource.prepStmtCacheSqlLimit: ${SW_DATA_SOURCE_PREP_STMT_CACHE_SQL_LIMIT:2048}
关键配置说明：
rewriteBatchedStatements=true：启用批量写入优化，提升数据入库性能cachePrepStmts系列参数：预编译语句缓存，减少数据库连接开销- 生产环境建议将密码通过环境变量传入，避免硬编码
步骤三：初始化数据库表结构SkyWalking 会自动创建所需表，首次启动时会执行初始化脚本。无需手动建表。
步骤四：启动 OAP 服务
# 启动后端服务（默认端口11800/12800）
./bin/oapService.sh start
# 查看启动日志
tail -f logs/skywalking-oap-server.log
步骤五：配置并启动 Web UI修改 webapp/webapp.yml：
server:
port: 8080 # UI访问端口
oap:
host: ${SW_OAP_HOST:localhost}
port: ${SW_OAP_PORT:12800}
启动UI服务：
./bin/webappService.sh start
访问 http://localhost:8080 即可进入监控控制台。
Docker快速部署方案
对于追求部署效率的场景，Docker 是最佳选择。SkyWalking 提供官方镜像，支持一键部署完整监控栈。
单机部署（开发测试）
1. 使用 Docker Compose创建 docker-compose.yml：
version: '3.8'
services:
oap:
image: apache/skywalking-oap-server:9.7.0
container_name: skywalking-oap
restart: always
ports:
- "11800:11800" # gRPC端口
- "12800:12800" # HTTP端口
environment:
SW_STORAGE: elasticsearch
SW_ES_USER: elastic
SW_ES_PASSWORD: your_password
SW_ES_URL: http://elasticsearch:9200
depends_on:
- elasticsearch
ui:
image: apache/skywalking-ui:9.7.0
container_name: skywalking-ui
restart: always
ports:
- "8080:8080"
environment:
SW_OAP_ADDRESS: http://oap:12800
depends_on:
- oap
elasticsearch:
image: elasticsearch:7.17.0
container_name: elasticsearch
restart: always
environment:
- discovery.type=single-node
- xpack.security.enabled=false
- "ES_JAVA_OPTS=-Xms512m -Xmx512m"
ports:
- "9200:9200"
volumes:
- es_data:/usr/share/elasticsearch/data
volumes:
es_data:
2. 启动服务
docker-compose up -d
3. 验证部署
# 检查容器状态
docker-compose ps
# 查看OAP日志
docker logs -f skywalking-oap
# 访问UI
curl http://localhost:8080
生产环境优化配置
生产环境需考虑高可用与性能优化：
1. 集群模式部署修改 OAP 环境变量：
environment:
SW_CLUSTER: kubernetes # 或zookeeper、nacos
SW_CLUSTER_K8S_NAMESPACE: skywalking
SW_CLUSTER_K8S_LABEL: app=skywalking
SW_CLUSTER_K8S_SERVICE_NAME: skywalking-oap
2. 资源限制
deploy:
resources:
limits:
memory: 2G
cpus: '2'
reservations:
memory: 1G
cpus: '1'
3. 数据持久化
volumes:
- ./data/oap:/skywalking/logs
- ./data/config:/skywalking/config
与现有监控体系集成
SkyWalking Docker 部署可轻松对接现有基础设施：
1. 对接外部 Elasticsearch
environment:
SW_STORAGE: elasticsearch
SW_ES_URL: http://your-es-cluster:9200
SW_ES_USER: ${ES_USER}
SW_ES_PASSWORD: ${ES_PASSWORD}
2. 配置反向代理（Nginx）
location /skywalking/ {
proxy_pass http://skywalking-ui:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
3. 监控数据导出通过 OAP 的 Prometheus 插件，将指标数据导出至现有监控系统：
environment:
SW_TELEMETRY_PROMETHEUS_HOST: 0.0.0.0
SW_TELEMETRY_PROMETHEUS_PORT: 1234
部署验证清单
部署完成后，执行以下验证步骤：
<图片>
可在此处配一张SkyWalking UI首页截图，展示服务拓扑图
- 服务连通性测试
# 测试OAP gRPC端口
grpcurl -plaintext localhost:11800 list
# 测试OAP HTTP端口
curl http://localhost:12800
# 测试UI访问
curl -I http://localhost:8080
- 数据上报验证启动一个测试应用并配置 SkyWalking Agent，观察数据是否正常上报至UI界面。
- 性能基准测试使用压测工具模拟业务流量，验证 SkyWalking 在高负载下的稳定性与资源消耗。
部署选择建议：
- 开发/测试环境：推荐 Docker Compose 单机部署，5分钟 完成环境搭建
- 预发布环境：使用 Docker 集群模式，模拟生产架构
- 生产环境：结合 Kubernetes 部署，配置资源限制与高可用策略
无论选择哪种部署方式，SkyWalking 都提供了灵活的配置选项，可根据实际需求调整存储后端、集群模式与资源分配。关键是要在部署初期明确监控数据的保留周期、存储容量规划以及告警策略，避免后期因数据膨胀或配置不当导致的运维负担。
四、Java语言对接使用方法
依赖配置与代理部署
1. 探针获取与部署方式
SkyWalking Java Agent 提供两种集成方式：独立探针部署与Maven依赖集成。对于生产环境，推荐使用独立探针方案，避免依赖冲突与版本管理问题。
独立探针部署步骤：
- 下载探针包从 SkyWalking 官网下载对应版本的发布包，解压后获取
agent/目录：
wget https://dlcdn.apache.org/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz
tar -zxvf apache-skywalking-apm-9.7.0.tar.gz
# 探针位于解压目录的 agent/ 子目录
- 探针目录结构解析
skywalking-agent/
├── config/ # 探针配置文件
│ └── agent.config # 核心配置文件
├── plugins/ # 插件目录（支持框架扩展）
│ ├── apm-spring-cloud-gateway-2.1.x-plugin.jar
│ ├── apm-dubbo-2.7.x-plugin.jar
│ └── ...
├── optional-plugins/ # 可选插件
├── bootstrap-plugins/ # 启动类插件
└── skywalking-agent.jar # 核心Agent JAR
- 基础配置参数编辑
config/agent.config或通过JVM参数动态配置：
# 服务名称（在UI中显示）
agent.service_name=${SW_AGENT_NAME:Your-Service-Name}
# OAP服务器地址（gRPC协议）
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800}
# 采样率（0.0-1.0，生产环境建议0.1-0.3）
agent.sample_n_per_3_secs=${SW_AGENT_SAMPLE:-1}
# 日志级别
logging.level=${SW_LOGGING_LEVEL:INFO}
2. 启动参数配置
传统JAR包启动方式：
java -javaagent:/path/to/skywalking-agent/skywalking-agent.jar \
-Dskywalking.agent.service_name=order-service \
-Dskywalking.collector.backend_service=192.168.1.100:11800 \
-Dskywalking.agent.sample_n_per_3_secs=100 \
-jar your-application.jar
Spring Boot应用启动脚本示例（start.sh）：
#!/bin/bash
AGENT_PATH="/opt/skywalking/agent/skywalking-agent.jar"
SERVICE_NAME="order-service"
OAP_SERVER="skywalking-oap:11800"
JVM_OPTS="-javaagent:${AGENT_PATH} \
-Dskywalking.agent.service_name=${SERVICE_NAME} \
-Dskywalking.collector.backend_service=${OAP_SERVER} \
-Dskywalking.logging.level=INFO \
-Dskywalking.agent.sample_n_per_3_secs=100 \
-Dskywalking.plugin.jdbc.trace_sql_parameters=true \
-Xms512m -Xmx512m"
java ${JVM_OPTS} -jar target/order-service-1.0.0.jar
关键参数说明：
-javaagent：必须放在所有JVM参数之前service_name：同一服务的多个实例应使用相 同名称backend_service：支持多个OAP地址，用逗号分隔实现负载均衡sample_n_per_3_secs：每3秒采样数，-1表示全量采集（仅限测试环境）
3. Maven/Gradle依赖集成（可选）
对于需要手动埋点或日志关联的场景，可添加Toolkit依赖：
Maven配置（pom.xml）：
<dependency>
<groupId>org.apache.skywalking</groupId>
<artifactId>apm-toolkit-trace</artifactId>
<version>9.7.0</version>
</dependency>
<dependency>
<groupId>org.apache.skywalking</groupId>
<artifactId>apm-toolkit-logback-1.x</artifactId>
<version>9.7.0</version>
</dependency>
<dependency>
<groupId>org.apache.skywalking</groupId>
<artifactId>apm-toolkit-opentracing</artifactId>
<version>9.7.0</version>
<scope>provided</scope>
</dependency>
Gradle配置（build.gradle）：
dependencies {
implementation 'org.apache.skywalking:apm-toolkit-trace:9.7.0'
implementation 'org.apache.skywalking:apm-toolkit-logback-1.x:9.7.0'
compileOnly 'org.apache.skywalking:apm-toolkit-opentracing:9.7.0'
}
<图片>
可在此处配一张IDEA中Maven依赖配置截图，展示SkyWalking依赖添加位置
代码示例与最佳实践
1. 自动埋点与框架支持
SkyWalking Java Agent 通过字节码增强技术自动支持主流框架：
Spring Boot 自动集成：Agent 自动识别并监控以下组件：
@RestController/@Controller注解的HTTP端点@Service/@Component业务服务层@Repository数据访问层- Spring MVC 请求映射与参数解析
- Spring Data JPA / MyBatis 数据库操作
支持框架列表：
- Web框架：Spring MVC 3.x/4.x/5.x, Spring Boot 1.x/2.x
- RPC框架：Dubbo 2.5.x-2.7.x, gRPC 1.x
- 消息队列：Kafka, RocketMQ 4.x
- 数据库：MySQL, PostgreSQL, Oracle, MongoDB
- 缓存：Redis (Jedis/Lettuce)
2. 手动埋点示例
对于自定义业务逻辑或第三方组件，可使用手动埋点：
Trace注解方式：
import org.apache.skywalking.apm.toolkit.trace.Trace;
import org.apache.skywalking.apm.toolkit.trace.TraceContext;
@Service
public class OrderService {
@Trace(operationName = "createOrder")
public OrderDTO createOrder(OrderRequest request) {
// 获取当前Trace ID（用于日志关联）
String traceId = TraceContext.traceId();
log.info("TraceID: {}, 开始创建订单", traceId);
// 业务逻辑
validateRequest(request);
Order order = buildOrder(request);
saveOrder(order);
return convertToDTO(order);
}
@Trace
private void validateRequest(OrderRequest request) {
// 参数校验逻辑
}
}
ActiveSpan API（更细粒度控制）：
import org.apache.skywalking.apm.toolkit.trace.ActiveSpan;
public class PaymentService {
public PaymentResult processPayment(PaymentRequest request) {
// 创建自定义Span
ActiveSpan.tag("payment_method", request.getMethod());
ActiveSpan.tag("amount", String.valueOf(request.getAmount()));
try {
ActiveSpan.debug("开始支付处理");
// 支付逻辑
return executePayment(request);
} catch (Exception e) {
// 标记错误
ActiveSpan.error(e);
ActiveSpan.tag("error_code", "PAYMENT_FAILED");
throw e;
}
}
}
3. 日志关联配置
将业务日志与Trace ID自动关联：
Logback配置（logback-spring.xml）：
<configuration>
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
<layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} - %msg%n</pattern>
</layout>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="CONSOLE" />
</root>
</configuration>
Log4j2配置：
<Configuration>
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%t] %-5p %c{1.} - %m%n"/>
</Console>
</Appenders>
<Loggers>
<Root level="info">
<AppenderRef ref="Console"/>
</Root>
</Loggers>
</Configuration>
日志输出示例：
2024-03-15 14:30:25.123 [TID:3.48.16893234250000001] [http-nio-8080-exec-1] INFO c.e.o.OrderService - 订单创建成功，订单号: ORD20240315001
4. 跨线程追踪
对于异步任务或线程池场景，需要手动传递Trace上下文：
Runnable/Callable包装：
import org.apache.skywalking.apm.toolkit.trace.RunnableWrapper;
import org.apache.skywalking.apm.toolkit.trace.CallableWrapper;
// 线程池提交任务
executorService.submit(RunnableWrapper.of(() -> {
// 异步任务逻辑，Trace上下文自动传递
processAsyncTask();
}));
// 带返回值的任务
Future<String> future = executorService.submit(
CallableWrapper.of(() -> {
return asyncCompute();
})
);
CompletableFuture支持：
import org.apache.skywalking.apm.toolkit.trace.TraceCrossThread;
@TraceCrossThread
public class TraceableCompletableFuture<T> extends CompletableFuture<T> {
// 自动继承Trace上下文
}
// 使用示例
TraceableCompletableFuture<String> future = new TraceableCompletableFuture<>();
executorService.submit(() -> {
String result = doAsyncWork();
future.complete(result);
});
5. 最佳实践总结
- 采样率配置：生产环境设置
agent.sample_n_per_3_secs=100（约3%采样），平衡监控开销与数据完整性。 - 插件管理：
plugins/目录只保留需要的插件，减少类加载开销。定期检查插件版本兼容性。 - 标签使用规范：
- 业务标签：
customer_id,order_type,payment_status - 技术标签：
db_instance,cache_hit,external_api - 避免标签值过大（超过512字节）
- 业务标签：
- 异常处理：关键业务方法使用
ActiveSpan.error(e)记录异常，结合@Trace注解的ignoreExceptions参数过滤已知异常。 - 性能监控：关注Agent的CPU和内存使用，单实例建议不超过应用资源的5%。
生产环境部署方案
1. 容器化部署策略
Docker镜像构建：
FROM openjdk:11-jre-slim
COPY skywalking-agent /usr/local/skywalking-agent
COPY target/app.jar /app/app.jar
ENTRYPOINT ["java", "-javaagent:/usr/local/skywalking-agent/skywalking-agent.jar", \
"-Dskywalking.agent.service_name=${SERVICE_NAME}", \
"-Dskywalking.collector.backend_service=${OAP_SERVER}", \
"-jar", "/app/app.jar"]
Kubernetes配置要点：
- 使用ConfigMap管理agent.config
- 通过环境变量注入服务名与OAP地址
- 设置资源限制：CPU 100m-500m，内存200M-1G
- 就绪探针检查Agent状态
2. 高可用架构
多OAP负载均衡：
agent.config: collector.backend_service=oap1:11800,oap2:11800,oap3:11800
服务发现集成：
- Kubernetes：通过Service名称自动发现
- Nacos/Zookeeper：动态获取OAP实例列表
- 客户端侧负载均衡与故障转移
3. 安全配置
认证与加密：
- gRPC TLS加密传输
- OAP访问令牌认证
- 网络策略限制访问范围
数据脱敏：
- SQL参数脱敏插件
- HTTP头信息过滤
- 自定义脱敏规则
4. 性能优化
采样策略：
- 关键路径全采样，非关键路径降采样
- 自适应采样：根据QPS动态调整
- 错误请求全采样
资源控制：
- 缓冲区大小优化
- 批量上报配置
- 离线模式支持（网络异常时）
5. 监控与运维
Agent自监控：
- 通过JMX暴露内部指标
- 健康检查端点
- 日志轮转与归档
升级与回滚：
- 蓝绿部署策略
- 版本兼容性矩阵
- 配置热更新支持
6. 故障排查清单
- 数据不上报：检查网络连通性、OAP状态、采样配置
- 高内存占用：调整缓冲区、减少插件、检查内存泄漏
- 性能影响：优化采样率、关闭非必要插件、升级版本
- Trace不完整：验证跨线程上下文传递、检查框架兼容性
部署验证：通过测试流量验证端到端监控链路，确保业务指标、Trace数据、日志关联三要素完整可用。
五、Python语言对接使用方法
SDK安装与环境配置
1. 安装方式与版本选择
SkyWalking Python探针通过apache-skywalking包提供，支持Python 3.6及以上版本。推荐使用虚拟环境隔离依赖：
# 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
# 安装SkyWalking Python SDK
pip install apache-skywalking
# 验证安装
python -c "import skywalking; print(skywalking.__version__)"
版本兼容性矩阵：
- SkyWalking Python SDK 1.x：支持SkyWalking OAP 8.x-9.x
- 建议使用最新稳定版（当前为1.0.0）
- 与后端OAP版本差异不超过2个大版本
2. 基础配置参数
Python SDK支持多种配置方式，优先级从高到低：环境变量 > 代码配置 > 配置文件。
核心配置项：
from skywalking import config
# 基础配置（必须）
config.init(
agent_collector_backend_services='127.0.0.1:11800', # OAP gRPC地址
agent_name='your-python-service', # 服务名称
agent_instance_name='instance-01', # 实例标识
agent_protocol='grpc', # 通信协议
agent_authentication='your-token', # 认证令牌（可选）
)
# 性能调优参数
config.agent_buffer_size = 1000 # 缓冲区大小
config.agent_queue_size = 5000 # 队列容量
config.agent_meter_reporter_period = 20 # 指标上报间隔（秒）
环境变量配置示例：
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=127.0.0.1:11800
export SW_AGENT_NAME=payment-service
export SW_AGENT_INSTANCE_NAME=payment-01
export SW_AGENT_PROTOCOL=grpc
export SW_AGENT_AUTHENTICATION=your-secret-token
Flask/Django框架集成示例
1. Flask应用集成
Flask集成通过中间件自动拦截HTTP请求，无需手动埋点：
from flask import Flask, jsonify
from skywalking import agent, config
# 初始化配置（必须在应用启动前调用）
config.init(
agent_collector_backend_services='127.0.0.1:11800',
agent_name='flask-demo',
agent_instance_name='flask-instance-01'
)
# 启动Agent
agent.start()
app = Flask(__name__)
# 自动追踪所有路由
@app.route('/api/orders/<int:order_id>', methods=['GET'])
def get_order(order_id):
"""获取订单详情 - 自动生成Span"""
# 业务逻辑
order_data = fetch_order_from_db(order_id)
return jsonify(order_data)
@app.route('/api/orders', methods=['POST'])
def create_order():
"""创建订单"""
from skywalking.trace.context import get_context
from skywalking.trace.tags import Tag
# 手动添加业务标签
context = get_context()
if context.active_span():
context.active_span().tag(Tag('order_type', 'standard'))
context.active_span().tag(Tag('customer_id', request.json.get('customer_id')))
# 业务处理
order_id = process_order_creation(request.json)
return jsonify({'order_id': order_id}), 201
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=False)
Flask特定配置：
# 启用HTTP参数收集（生产环境谨慎开启）
config.flask_collect_http_params = True
# 排除特定路由（如健康检查）
config.flask_ignore_path = ['/health', '/metrics']
# 请求体大小限制（避免内存溢出）
config.flask_collect_http_body_length_limit = 1024 # 字节
2. Django应用集成
Django通过中间件实现自动追踪：
settings.py配置：
INSTALLED_APPS = [
# ... 其他应用
'skywalking',
]
MIDDLEWARE = [
'skywalking.contrib.django.middleware.TracingMiddleware', # 必须放在最前
# ... 其他中间件
]
# SkyWalking配置
SKYWALKING_CONFIG = {
'agent_collector_backend_services': '127.0.0.1:11800',
'agent_name': 'django-ecommerce',
'agent_instance_name': 'django-instance-01',
'agent_protocol': 'grpc',
'django_collect_http_params': False, # 生产环境建议关闭
'django_ignore_path': ['/admin/', '/static/', '/media/'],
}
视图函数示例：
from django.http import JsonResponse
from skywalking.trace.context import get_context
from skywalking.trace.tags import Tag
def product_detail(request, product_id):
"""商品详情页 - 自动追踪"""
context = get_context()
# 手动添加业务维度
if context.active_span():
span = context.active_span()
span.tag(Tag('product_id', product_id))
span.tag(Tag('user_agent', request.META.get('HTTP_USER_AGENT', '')))
# 业务逻辑
product = Product.objects.get(id=product_id)
return JsonResponse({
'id': product.id,
'name': product.name,
'price': product.price
})
# 异步视图支持（Django 3.1+）
async def async_product_list(request):
"""异步商品列表"""
from skywalking.contrib.async_trace import async_trace
@async_trace(operation_name='async_product_query')
async def fetch_products():
return await Product.objects.all().alist()
products = await fetch_products()
return JsonResponse({'products': products})
配置项详解
1. 探针核心配置
网络与连接配置：
config.init(
# 连接设置
agent_collector_backend_services='127.0.0.1:11800,192.168.1.100:11800', # 多OAP负载均衡
agent_protocol='grpc', # grpc或http
agent_grpc_tls_enable=False, # TLS加密
agent_grpc_tls_cert_path='/path/to/cert.pem',
# 超时与重试
agent_collector_grpc_upstream_timeout=30, # 秒
agent_collector_grpc_max_retry=3,
agent_collector_grpc_retry_interval=1, # 秒
)
采样与性能配置：
# 采样策略
config.agent_sample_rate = 0.1 # 10%采样率（0.0-1.0）
config.agent_force_sample_error = True # 错误请求强制采样
# 缓冲区管理
config.agent_buffer_size = 1000 # 单次批量上报最大Span数
config.agent_queue_size = 5000 # 内存队列容量
config.agent_meter_reporter_period = 20 # 指标上报周期（秒）
# 资源限制
config.agent_max_buffer_size = 10000 # 最大缓冲区
config.agent_disable_oom_protection = False # OOM保护
2. 框架特定配置
HTTP框架通用配置：
# 请求/响应追踪
config.collect_http_params = False # 是否收集HTTP参数
config.http_params_length_threshold = 1024 # 参数长度限制
config.trace_ignore_path = ['/health', '/metrics', '/docs'] # 忽略路径
# 数据库操作追踪
config.sql_parameters_max_length = 512 # SQL参数截断长度
config.trace_sql_parameters = False # 是否记录SQL参数（安全考虑）
# 外部调用追踪
config.redis_parameters_max_length = 256 # Redis参数限制
config.mq_parameters_max_length = 512 # 消息队列参数限制
插件管理配置：
# 启用/禁用特定插件
config.plugin_enable = {
'flask': True,
'django': True,
'requests': True, # HTTP客户端追踪
'urllib3': True, # 低级HTTP库追踪
'mysql': True, # MySQL数据库
'redis': True, # Redis缓存
'pymongo': True, # MongoDB
'kafka': True, # Kafka消息
'grpc': True, # gRPC调用
}
# 自定义插件路径
config.plugin_mount_dir = '/path/to/custom/plugins'
3. 日志与诊断配置
日志集成：
# 自动注入Trace ID到日志
config.log_reporter_active = True
config.log_reporter_level = 'WARNING' # 日志级别阈值
config.log_reporter_formatted = True # 格式化输出
# 日志采样（避免日志爆炸）
config.log_reporter_sample_rate = 0.01 # 1%日志采样
诊断与监控：
# 健康检查端点
config.agent_health_check = True
config.agent_health_check_port = 8081 # 健康检查端口
# JMX监控
config.agent_jmx_active = True
config.agent_jmx_port = 9090
# 调试模式（仅开发环境）
config.agent_debug = False
config.agent_logging_level = 'INFO' # DEBUG, INFO, WARNING, ERROR
4. 高级特性配置
跨进程传播：
# HTTP头传播配置
config.propagation_header_name = 'sw8' # SkyWalking标准头
config.propagation_header_encode = 'base64'
# 自定义传播器
config.propagation_cross_process_propagators = [
'sw8',
'b3', # Zipkin兼容
'traceparent', # W3C Trace Context
]
# 消息队列传播
config.kafka_bootstrap_servers = 'localhost:9092'
config.kafka_propagation_topic = 'skywalking-trace'
安全与隐私：
# 数据脱敏
config.mask_sql_parameters = True # SQL参数脱敏
config.mask_http_params = ['password', 'token', 'secret'] # HTTP参数黑名单
# 访问控制
config.agent_authentication = 'your-service-token'
config.agent_authorization = 'Bearer xxxxx'
# 网络隔离
config.agent_network_isolation = True
config.agent_allowed_backend_services = ['192.168.1.0/24']
5. 环境变量覆盖表
| 环境变量 | 对应配置项 | 默认值 | 说明 |
|---|---|---|---|
| SW_AGENT_NAME | agent_name | - | 服务名称（必填） |
| SW_AGENT_INSTANCE_NAME | agent_instance_name | 随机生成 | 实例标识 |
| SW_AGENT_COLLECTOR_BACKEND_SERVICES | agent_collector_backend_services | - | OAP地址（必填） |
| SW_AGENT_PROTOCOL | agent_protocol | grpc | 通信协议 |
| SW_AGENT_AUTHENTICATION | agent_authentication | - | 认证令牌 |
| SW_AGENT_SAMPLE_RATE | agent_sample_rate | 1.0 | 采样率 |
| SW_AGENT_BUFFER_SIZE | agent_buffer_size | 1000 | 缓冲区大小 |
| SW_AGENT_QUEUE_SIZE | agent_queue_size | 5000 | 队列容量 |
| SW_AGENT_LOGGING_LEVEL | agent_logging_level | INFO | 日志级别 |
| SW_AGENT_DEBUG | agent_debug | False | 调试模式 |
6. 配置验证与诊断
配置验证脚本：
from skywalking import config
def validate_config():
"""验证配置完整性"""
required_configs = [
'agent_collector_backend_services',
'agent_name'
]
missing = []
for key in required_configs:
if not getattr(config, key, None):
missing.append(key)
if missing:
raise ValueError(f"缺少必要配置: {missing}")
# 检查网络连通性
import socket
for backend in config.agent_collector_backend_services.split(','):
host, port = backend.split(':')
try:
sock = socket.create_connection((host, int(port)), timeout=5)
sock.close()
print(f"✓ 可连接到 {backend}")
except Exception as e:
print(f"✗ 无法连接到 {backend}: {e}")
运行时诊断：
# 获取Agent状态
from skywalking.agent import agent
print(f"Agent状态: {'运行中' if agent.running else '已停止'}")
print(f"已发送Span数: {agent.metrics.spans_sent}")
print(f"队列使用率: {agent.metrics.queue_usage_percent}%")
# 手动触发指标上报
agent.report_metrics()
# 强制刷新缓冲区
agent.flush()
最佳实践建议：
- 生产环境配置：通过环境变量管理敏感信息，避免硬编码
- 采样策略：关键业务接口设置较高采样率（0.3-0.5），非关键接口降低采样率（0.05-0.1）
- 缓冲区调优：根据QPS调整缓冲区大小，高流量服务适当增大
agent_buffer_size - 安全考虑：生产环境关闭
collect_http_params和trace_sql_parameters，避免敏感信息泄露 - 监控告警：设置队列使用率、发送失败率等监控指标，及时发现Agent异常
通过合理配置，Python SDK可在不影响应用性能的前提下，提供完整的可观测性数据。建议在预发布环境充分测试配置效果，确保生产环境稳定运行。
六、Go语言对接使用方法
两种集成方式对比
| 维度 | Agent注入方式 | 代码依赖方式 |
|---|---|---|
| 原理 | 二进制注入，修改Go编译输出 | 导入SDK包，代码级集成 |
| 侵入性 | 无代码侵入 | 需修改import语句 |
| 部署复杂度 | 高（需构建环境） | 低（标准go get） |
| 灵活性 | 低（配置驱动） | 高（API可编程） |
| 适用场景 | 存量项目快速接入 | 新建项目深度集成 |
注入方式详细步骤
- 下载Agent工具：从SkyWalking官网获取对应平台的二进制文件
- 注入命令：
/path/to/agent -inject /path/to/your/project [-all] - 配置管理：通过
config.yaml文件设置服务名、OAP地址 - 构建部署：正常执行
go build，Agent自动修改二进制
关键限制：
- 仅支持标准Go工具链
- 需在构建阶段执行
- 不支持动态配置更新
代码依赖配置方法
基础集成：
import _ "github.com/apache/skywalking-go"
配置示例（config.yaml）：
agent:
service_name: "order-service"
reporter:
grpc:
backend_service: "127.0.0.1:11800"
authentication: "your-token"
框架支持：
- Web框架：Gin, Echo, Beego, Iris
- RPC：gRPC, Dubbo-go
- 数据库：GORM, SQLx, MongoDB驱动
- 消息队列：Sarama(Kafka), NSQ
手动埋点示例：
import "github.com/apache/skywalking-go/trace"
func ProcessOrder(ctx context.Context) {
span, ctx := trace.CreateEntrySpan(ctx, "order.process")
defer span.End()
span.Tag(trace.StringTag("order_type", "standard"))
// 业务逻辑
}
选择建议：新项目用代码依赖，存量系统用Agent注入。
七、监控与调优建议
基础配置建议
- 采样率：生产环境0.1-0.3，关键业务0.5
- 缓冲区：根据QPS调整，默认1000-5000
- 存储：生产用Elasticsearch，测试可用H2/MySQL
常见问题排查
- 数据不上报：检查网络、OAP状态、Agent配置
- 高内存：调小缓冲区，减少插件，检查版本
- Trace不全：验证跨线程传播，检查框架兼容性
性能优化技巧
- 网络：启用gRPC压缩，配置多OAP负载均衡
- 存储：ES分片优化，索引生命周期管理
- Agent：关闭非必要插件，调整上报频率
- 业务：关键路径全采样，错误请求强制采样