链路

不适用。

1. 使用 StartTransaction 启动事务，或使用 StartSpan 启动 span。
2. 获取活动的 TraceContext。
3. 将 TraceContext 发送到接收服务。

示例

transaction := apm.DefaultTracer().StartTransaction("GET /", "request")
traceContext := transaction.TraceContext()

// Send TraceContext to receiving service
traceparent := apmhttp.FormatTraceparentHeader(traceContext)
tracestate := traceContext.State.String()

1. 启动事务
2. 从当前事务获取 TraceContext
3. 将 TraceContext 或 tracestate 格式化为 traceparent 标头。

该代理将自动将链路标头注入到使用 URLSessions 的网络请求中，但是如果您使用非标准网络库，您可能需要手动注入它们。 这将使用 OpenTelemetry API 完成

1. 创建一个 Setter
2. 根据 Open Telemetry 标准 创建一个 Span
3. 将链路上下文注入到标头字典中
4. 按照您的网络库的步骤完成网络请求。 确保在请求成功或失败时调用 span.end()。

import OpenTelemetryApi
import OpenTelemetrySdk

struct BasicSetter: Setter {
    func set(carrier: inout [String: String], key: String, value: String) {
        carrier[key] = value
    }
}

let span : Span = ...
let setter = BasicSetter()
let propagator = W3CTraceContextPropagator()
var headers = [String:String]()

propagator.inject(spanContext: span.context, carrier: &headers, setter:setter)

let request = URLRequest(...)
request.allHTTPHeaderFields = headers
...
span.end()

1. 使用 startTransaction 启动事务，或使用 startSpan 启动 span。
2. 使用 injectTraceHeaders 将 traceparent 标头注入到请求对象中
3. 发出网络请求

手动检测 RPC 框架的示例

// Hook into a callback provided by the RPC framework that is called on outgoing requests
public Response onOutgoingRequest(Request request) throws Exception {
  Span span = ElasticApm.currentSpan()
          .startSpan("external", "http", null)
          .setName(request.getMethod() + " " + request.getHost());
  try (final Scope scope = transaction.activate()) {
      span.injectTraceHeaders((name, value) -> request.addHeader(name, value));
      return request.execute();
  } catch (Exception e) {
      span.captureException(e);
      throw e;
  } finally {
      span.end();
  }
}

1. 创建一个表示外部调用的 span
2. 将 traceparent 标头注入到请求对象中
3. 结束 span

1. 使用 CurrentTransaction 或 CurrentSpan 序列化活动事务或 span 的分布式链路追踪上下文。
2. 将序列化的上下文发送到接收服务。

示例

string outgoingDistributedTracingData =
    (Agent.Tracer.CurrentSpan?.OutgoingDistributedTracingData
        ?? Agent.Tracer.CurrentTransaction?.OutgoingDistributedTracingData)?.SerializeToString();
// Now send `outgoingDistributedTracingData` to the receiving service

1. 使用 apm.startTransaction() 启动事务，或使用 apm.startSpan() 启动 span。
2. 使用 currentTraceparent 获取启动的事务/span 的序列化 traceparent 字符串。
3. 对 traceparent 进行编码，并在常规请求中将其发送到接收服务。

使用原始 UDP 在两个服务 A 和 B 之间进行通信的示例

agent.startTransaction('my-service-a-transaction');
const traceparent = agent.currentTraceparent;
sendMetadata(`traceparent: ${traceparent}\n`);

1. 启动事务
2. 获取当前的 traceparent
3. 将 traceparent 作为标头发送到服务 B。

1. 在客户端（即发送请求的一方）获取当前分布式链路追踪上下文。
2. 将当前分布式链路追踪上下文序列化为请求传输支持的格式，并将其发送到服务器端（即接收请求的一方）。

示例

$distDataAsString = ElasticApm::getSerializedCurrentDistributedTracingData();

1. 获取序列化为字符串的当前分布式链路追踪数据

1. 使用 begin_transaction() 启动事务。
2. 获取活动事务的 trace_parent。
3. 将 trace_parent 发送到接收服务。

示例

client.begin_transaction('new-transaction')<1>

elasticapm.get_trace_parent_header('new-transaction')

# Send `trace_parent_str` to another service

1. 启动新事务
2. 返回当前事务的 TraceParent 对象的字符串表示形式

1. 使用 with_span 启动 span。
2. 获取活动的 TraceContext。
3. 将 TraceContext 发送到接收服务。

ElasticAPM.with_span "Name" do |span|
  header = span.trace_context.traceparent.to_header
  # send the TraceContext Header to a receiving service...
end

1. 启动 span
2. 获取 TraceContext

不适用。

1. 使用 ParseTraceparentHeader 或 ParseTracestateHeader 解析传入的 TraceContext。
2. 使用 StartTransactionOptions 或 StartSpanOptions，启动一个新的事务或 span 作为传入事务的子项。

示例

// Receive incoming TraceContext
traceContext, _ := apmhttp.ParseTraceparentHeader(r.Header.Get("Traceparent"))
traceContext.State, _ = apmhttp.ParseTracestateHeader(r.Header["Tracestate"]...)

opts := apm.TransactionOptions{
  TraceContext: traceContext,
}
transaction := apm.DefaultTracer().StartTransactionOptions("GET /", "request", opts)

1. 解析 TraceParent 标头
2. 解析 Tracestate 标头
3. 设置父跟踪上下文
4. 启动一个新的事务，作为接收到的 TraceContext 的子项

不适用。

1. 创建一个事务，作为传入事务的子项，使用 startTransactionWithRemoteParent()。
2. 使用 activate() 和 setName() 启动并命名事务。

示例

// Hook into a callback provided by the framework that is called on incoming requests
public Response onIncomingRequest(Request request) throws Exception {
    // creates a transaction representing the server-side handling of the request
    Transaction transaction = ElasticApm.startTransactionWithRemoteParent(request::getHeader, request::getHeaders);
    try (final Scope scope = transaction.activate()) {
        String name = "a useful name like ClassName#methodName where the request is handled";
        transaction.setName(name);
        transaction.setType(Transaction.TYPE_REQUEST);
        return request.handle();
    } catch (Exception e) {
        transaction.captureException(e);
        throw e;
    } finally {
        transaction.end();
    }
}

1. 创建一个事务，作为远程父级的子项
2. 激活事务
3. 命名事务
4. 添加事务类型
5. 最终，结束事务

反序列化传入的分布式跟踪上下文，并将其传递给任何 StartTransaction 或 CaptureTransaction API — 它们都有一个可选的 DistributedTracingData 参数。 这将创建一个新的事务或 span 作为传入跟踪上下文的子项。

启动新事务的示例

var transaction2 = Agent.Tracer.StartTransaction("Transaction2", "TestTransaction",
     DistributedTracingData.TryDeserializeFromString(serializedDistributedTracingData));

1. 在接收服务中解码并存储 traceparent。
2. 将 traceparent 作为 childOf 选项传递，以手动启动一个新事务，作为接收到的 traceparent 的子项，使用 apm.startTransaction()。

通过原始 UDP 接收 traceparent 的示例

const traceparent = readTraceparentFromUDPPacket()
agent.startTransaction('my-service-b-transaction', { childOf: traceparent })

1. 从传入的请求中读取 traceparent。
2. 使用 traceparent 初始化一个新事务，该事务是原始 traceparent 的子项。

1. 在服务器端接收分布式跟踪数据。
2. 使用代理的公共 API 开始一个新事务。 例如，使用 ElasticApm::beginCurrentTransaction 并将接收到的分布式跟踪数据（序列化为字符串）作为参数传递。 这将创建一个新的事务，作为传入跟踪上下文的子项。
3. 不要忘记最终在服务器端结束事务。

示例

$receiverTransaction = ElasticApm::beginCurrentTransaction(
    'GET /data-api',
    'data-layer',
    /* timestamp */ null,
    $distDataAsString
);

1. 启动新事务
2. 传入接收到的分布式跟踪数据（序列化为字符串）

在接收服务中创建了新的事务后，您可以创建子 span，或者使用您通常使用的任何其他代理 API 方法。

1. 从字符串或 HTTP 标头创建 TraceParent 对象。
2. 通过传入 TraceParent 对象，启动一个新的事务，作为 TraceParent 的子项。

使用 HTTP 标头的示例

parent = elasticapm.trace_parent_from_headers(headers_dict)
client.begin_transaction('processors', trace_parent=parent)

1. 从形成字典的 HTTP 标头创建 TraceParent 对象
2. 开始一个新事务，作为接收到的 TraceParent 的子项

使用 with_transaction 或 with_span，启动一个新的事务或 span 作为传入事务或 span 的子项。

示例

# env being a Rack env
context = ElasticAPM::TraceContext.parse(env: env)

ElasticAPM.with_transaction("Do things", trace_context: context) do
  ElasticAPM.with_span("Do nested thing", trace_context: context) do
  end
end

1. 解析传入的 TraceContext
2. 创建一个事务，作为传入的 TraceContext 的子项
3. 创建 span 作为新创建的事务的子项。 在这里，trace_context 是可选的，因为 span 在没有传递 trace_context 的情况下，将自动创建为父事务的 TraceContext 的子项。