skywalking sdk

项目背景与战略目标

skywalking sdk 是一个面向仓颉编程语言（Cangjie Language）生态的分布式应用性能监控（APM）客户端库，用于在微服务、云原生及 Kubernetes 环境中自动采集追踪（Tracing）、指标（Metrics）和日志（Logs）数据，并上报至 Apache SkyWalking 后端。该项目属于后端可观测性基础设施的核心组件，为仓颉应用提供开箱即用的性能监控、链路追踪与异常诊断能力。依托仓颉语言 1.0.0+ 的内存安全特性（彻底消除因上下文传播或缓冲区操作引发的 CVE 风险）、轻量级线程模型（高并发场景下低开销采样）、强类型系统（确保 Span 与标签结构正确）以及 CJNative 高性能 FFI 能力（高效对接 eBPF 或系统调用），本项目旨在打造一个零侵入、高性能、协议兼容的 APM SDK，填补仓颉在云原生可观测性领域的空白，赋能开发者构建高可靠、可运维的分布式系统。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：单次 Span 创建开销 ≤1μs，P99 上报延迟 < 10ms（局域网），CPU 占用 < 3%（1K QPS）。

• 安全要求：所有上下文字段受强类型约束；敏感标签（如 token）可配置过滤；无 unsafe 代码。

• 可靠性：上报失败自动重试 + 本地缓存；极端负载下自动采样降级，不阻塞主业务。

• 可维护性：模块解耦（tracing/metrics/reporting 分离）；支持插件化扩展（如自定义采样策略）。

2.3 核心接口设计示例 (伪代码)

interface SkyWalkingTracer {
    // 创建根 Span
    fn startRootSpan(self, operation: String) -> Span;

    // 从上下文提取并创建子 Span
    fn extractAndStartSpan(self, carrier: &ContextCarrier) -> Span;

    // 注入上下文到载体（如 HTTP Headers）
    fn inject(self, span: &Span, carrier: &mut ContextCarrier);
}

struct Span {
    traceId: String,
    spanId: u64,
    parentSpanId: Option<u64>,
    operationName: String,
    startTime: Timestamp,
}

impl Span {
    // RAII：析构时自动结束并上报
    fn end(self);
}

enum SkyWalkingError {
    NetworkFailure(IoError),
    InvalidContext(String),
    ReporterQueueFull,
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：基础 Tracing 上下文传播 + Span 管理 + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：Metrics 采集 + gRPC/HTTP 上报通道 + 与 SkyWalking OAP 集成测试

• 第三阶段：自动采样策略 + 性能调优报告 + cjpm 发布包

3.2 项目实施路线图

技术实现规范与质量认证体系

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt 格式校验；禁止裸指针和全局可变状态。

• 类型安全：Span 字段不可变；上下文载体使用泛型适配不同协议（HTTP/gRPC）。

• 错误处理：所有 I/O 操作返回 Result<T, E>；错误类型枚举覆盖网络、协议、资源三类。

4.2 测试与验证标准

• 单元测试：覆盖上下文注入/提取、Span 嵌套、上报失败等场景，行覆盖率 ≥95%。

• 互操作测试：与 SkyWalking 官方 Java Agent 构建混合链路，验证 Trace 连续性。

• 安全扫描：通过 cjpm lint --deny-unsafe 和内存安全静态分析。

4.3 文档与可维护性

• 所有 public 接口包含 Doc Comments，说明线程安全性和生命周期约束。

• 记录上下文传播模型、上报协议选型（OTLP vs SkyWalking Native）等 ADR。

• 提供 skywalking-cj-example 示例项目及贡献指南。

4.4 持续集成质量门禁

# PR 自动化流水线
cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings --deny-unsafe
cjpm test --all-features --coverage
cjpm bench

技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0+

• 构建与包管理：CJPM (Cangjie Package Manager)

• 依赖组件：cj-grpc（gRPC 上报）、cj-http（HTTP 上报）、cj-otel（OpenTelemetry 兼容层）

• 测试框架：@cangjie/test + SkyWalking OAP Docker 集成测试

• 环境要求：仓颉 1.0.0+ 标准工具链；CI 使用 cangjie-lang/cj-builder:1.0 官方 Docker 镜像

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求