https://github.com/fujiwara/aws-xray

AWS X-Ray tracing library for Perl5
https://github.com/fujiwara/aws-xray

aws perl x-ray

Last synced: 3 days ago
JSON representation

AWS X-Ray tracing library for Perl5

• Host: GitHub
• URL: https://github.com/fujiwara/aws-xray
• Owner: fujiwara
• License: other
• Created: 2018-06-14T14:45:47.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2022-05-11T03:51:03.000Z (over 2 years ago)
• Last Synced: 2024-09-24T19:51:52.021Z (3 days ago)
• Topics: aws, perl, x-ray
• Language: Perl
• Homepage:
• Size: 90.8 KB
• Stars: 6
• Watchers: 4
• Forks: 8
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

        
# NAME

AWS::XRay - AWS X-Ray tracing library

# SYNOPSIS

    use AWS::XRay qw/ capture /;

    capture "myApp", sub {

        capture "remote", sub {

            # do something ...

            capture "nested", sub {

                # ...

            };

        };

        capture "myHTTP", sub {

            my $segment = shift;

            # ...

            $segment->{http} = { # modify segment document

                request => {

                    method => "GET",

                    url    => "http://localhost/",

                },

                response => {

                    status => 200,

                },

            };

        };

    };

    my $header;

    capture "source", sub {

        my $segment = shift;

        $header = $segment->trace_header;

    };

    capture_from $header, "dest", sub {

        my $segment = shift;  # is a child of "source" segment

        # ...

    };

# DESCRIPTION

AWS::XRay is a tracing library with AWS X-Ray.

AWS::XRay sends segment data to [AWS X-Ray Daemon](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html).

# FUNCTIONS

## new\_trace\_id

Generate a Trace ID. (e.g. "1-581cf771-a006649127e371903a2de979")

[Document](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids)

## capture($name, $code)

capture() executes $code->($segment) and send the segment document to X-Ray daemon.

$segment is a AWS::XRay::Segment object.

When $AWS::XRay::TRACE\_ID is not set, generates TRACE\_ID automatically.

When capture() called from other capture(), $segment is a sub segment document.

See also [AWS X-Ray Segment Documents](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html).

## capture\_from($header, $name, $code)

capture\_from() parses the trace header and capture the $code with sub segment of header's segment.

## parse\_trace\_header($header)

    my ($trace_id, $segment_id) = parse_trace_header($header);

Parse a trace header (e.g. "Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8").

## add\_capture($package, $method1\[, $method2, ...\])

add\_capture() adds a capture to package::method.

    AWS::XRay->add_capture("MyApp::Model", "foo", "bar");

The segments of these captures are named as "MyApp::Model".

These segments include metadata "method": "foo" or "bar".

# CONFIGURATION

## sampling\_rate($rate)

Set/Get a sampling rate for capture().

    AWS::XRay->sampling_rate(0.1); # 10% sampling

$rate is allowed a float value between 0 and 1.

0 means disable tracing.

1 means all of capture() are traced.

When capture\_from() called with a trace header includes "Sampled=1", all of followed capture() are traced.

## sampler($code)

Set/Get a code ref to sample for capture().

    AWS::XRay->sampler(sub {

        if ($some_condition) {

           return 1;

        } else {

           return 0;

        }

    });

## auto\_flush($mode)

Set/Get auto flush mode.

When $mode is 1 (default), segment data will be sent to xray daemon immediately after capture() called.

When $mode is 0, segment data are buffered in memory. You should call AWS::XRay->sock->flush() to send the buffered segment data or call AWS::XRay->sock->close() to discard the buffer.

## AWS\_XRAY\_DAEMON\_ADDRESS environment variable

Set the host and port of the X-Ray daemon. Default 127.0.0.1:2000

## $AWS::XRay::CROAK\_INVALID\_NAME

When set to 1 (default 0), capture() will raise exception if a segment name is invalid.

See https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html

> name – The logical name of the service that handled the request, up to 200 characters.

> For example, your application's name or domain name.

> Names can contain Unicode letters, numbers, and whitespace, and the following symbols: \_, ., :, /, %, &, #, =, +, \\, -, @

# LICENSE

Copyright (C) FUJIWARA Shunichiro.

This library is free software; you can redistribute it and/or modify

it under the same terms as Perl itself.

# AUTHOR

FUJIWARA Shunichiro