Migrate from AWS X-Ray to TraceKit
AWS X-Ray locks your tracing into the AWS ecosystem. TraceKit gives you the same distributed tracing visibility across any cloud, any infrastructure, with a single SDK.
Migration Steps
Replace X-Ray SDK with TraceKit SDK
Remove the AWS X-Ray SDK and install TraceKit. X-Ray uses segments and subsegments; TraceKit uses spans. The X-Ray daemon is no longer needed -- TraceKit sends traces directly via HTTPS.
| Category | Before | After (TraceKit) | Notes |
|---|---|---|---|
| Package | aws-xray-sdk-go (Go) | github.com/tracekit/go-sdk | Go SDK replacement |
| Package | aws-xray-sdk-node (npm) | @tracekit/node-apm (npm) | Node.js SDK replacement |
| Package | aws-xray-sdk (pip) | tracekit-apm (pip) | Python SDK replacement |
Remove X-Ray Daemon and Map Configuration
The X-Ray daemon is a UDP listener that buffers and forwards segments to AWS. TraceKit SDKs send directly via HTTPS -- remove the daemon container or sidecar from your deployment.
| Category | Before | After (TraceKit) | Notes |
|---|---|---|---|
| Daemon | AWS_XRAY_DAEMON_ADDRESS (default 127.0.0.1:2000) | (not needed) | No daemon; SDK sends directly to endpoint |
| Daemon | X-Ray daemon container/sidecar | (remove from deployment) | Remove daemon from ECS task/K8s pod spec |
| Authentication | AWS IAM role (xray:PutTraceSegments) | TRACEKIT_API_KEY | API key replaces IAM-based auth |
| Service Identity | AWS_XRAY_TRACING_NAME | TRACEKIT_SERVICE_NAME | Service name for trace grouping |
Migrate Segments and Subsegments to Spans
X-Ray's segment concept maps to a root span, and subsegments map to child spans. Replace BeginSegment/BeginSubsegment calls with TraceKit span creation using context propagation.
| Category | Before | After (TraceKit) | Notes |
|---|---|---|---|
| Segments | xray.BeginSegment(ctx, name) | tracekit.StartSpan(ctx, name) | Segments become root spans |
| Subsegments | xray.BeginSubsegment(ctx, name) | tracekit.StartSpan(ctx, name) | Subsegments become child spans (context links parent) |
| Close | seg.Close(err) | span.End() | Close maps to End; errors recorded separately |
| Annotations | seg.AddAnnotation(key, value) | span.SetAttribute(key, value) | Annotations (indexed) become attributes |
| Metadata | seg.AddMetadata(key, value) | span.SetAttribute(key, value) | Metadata (non-indexed) also becomes attributes |
Update AWS Service Integrations
X-Ray auto-instruments AWS SDK calls (DynamoDB, S3, SQS, Lambda). With TraceKit, instrument these calls using middleware or manual spans. TraceKit works across all clouds, not just AWS.
| Category | Before | After (TraceKit) | Notes |
|---|---|---|---|
| AWS SDK | xray.AWS(awsClient) (auto-instrument) | tracekit.WrapHTTPClient(client) | HTTP client wrapper captures outbound calls |
| Lambda | X-Ray active tracing (Lambda console toggle) | TraceKit SDK in Lambda handler | Add SDK init to Lambda handler function |
| Sampling | xray.Configure({DaemonAddr, SamplingStrategy}) | tracekit.WithSampleRate(rate) | SDK-level sampling configuration |
Verify Traces Across Clouds
Deploy and verify traces in TraceKit. Unlike X-Ray, TraceKit traces can span AWS, GCP, Azure, and on-premise services in a single view. Disable X-Ray active tracing on your AWS services once TraceKit is confirmed working.
| Category | Before | After (TraceKit) | Notes |
|---|---|---|---|
| Verification | AWS Console > X-Ray > Traces | TraceKit Dashboard > Traces | Verify trace waterfall and service map |
| Verification | X-Ray Service Map | TraceKit Service Map | Verify cross-service dependencies |
| Cleanup | Disable X-Ray active tracing on AWS services | (keep TraceKit running) | Turn off X-Ray to avoid double-billing |
Code Examples
import (
"github.com/aws/aws-xray-sdk-go/xray"
)
func main() {
xray.Configure(xray.Config{
DaemonAddr: "127.0.0.1:2000",
ServiceVersion: "1.0.0",
})
ctx, seg := xray.BeginSegment(context.Background(), "my-service")
defer seg.Close(nil)
_, subseg := xray.BeginSubsegment(ctx, "fetch-data")
subseg.AddAnnotation("user.id", "u-123")
// ... business logic
subseg.Close(nil)
}import "github.com/tracekit/go-sdk/tracekit"
func main() {
tracekit.Init("tk_your_api_key",
tracekit.WithService("my-service"),
tracekit.WithEnvironment("production"),
)
defer tracekit.Shutdown(context.Background())
ctx, span := tracekit.StartSpan(context.Background(), "my-service")
defer span.End()
_, child := tracekit.StartSpan(ctx, "fetch-data")
child.SetAttribute("user.id", "u-123")
// ... business logic
child.End()
}const AWSXRay = require('aws-xray-sdk-core');
AWSXRay.setDaemonAddress('127.0.0.1:2000');
const segment = new AWSXRay.Segment('my-service');
const subsegment = segment.addNewSubsegment('fetch-data');
subsegment.addAnnotation('user_id', 'u-123');
// ... business logic
subsegment.close();
segment.close();const tracekit = require('@tracekit/node-apm');
tracekit.init({
apiKey: 'tk_your_api_key',
service: 'my-service',
environment: 'production',
});
const span = tracekit.startSpan('my-service');
const child = tracekit.startSpan('fetch-data', { parent: span });
child.setAttribute('user_id', 'u-123');
// ... business logic
child.end();
span.end();from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(
daemon_address='127.0.0.1:2000',
service='my-service',
)
segment = xray_recorder.begin_segment('my-service')
subsegment = xray_recorder.begin_subsegment('fetch-data')
subsegment.put_annotation('user_id', 'u-123')
# ... business logic
xray_recorder.end_subsegment()
xray_recorder.end_segment()import tracekit
tracekit.init(
api_key='tk_your_api_key',
service='my-service',
environment='production',
)
with tracekit.start_span('my-service') as span:
with tracekit.start_span('fetch-data') as child:
child.set_attribute('user_id', 'u-123')
# ... business logic