Skip to content

Commit b1abf47

Browse files
Kausik-AKausik-A
authored
Merge branch 'main' into lambdadocchnage
2 parents 62918fd + 00252ea commit b1abf47

File tree

7 files changed

+292
-5
lines changed

7 files changed

+292
-5
lines changed

‎src/config/sideBarData.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ export const sideBarData = [
6161
{label: "Python", link: "/docs/getting-started/python-sdk"},
6262
{label: "Ruby", link: "/docs/getting-started/ruby-sdk"},
6363
{label: ".NET", link: "/docs/getting-started/dotnet-sdk"},
64+
{label: "PHP", link: "/docs/getting-started/php-sdk"},
6465
{label: "k8s Operator", link: "/docs/getting-started/operator"},
6566
{label: "ADOT with EKS add-ons", link: "/docs/getting-started/adot-eks-add-on"},
6667
{label: "Lambda", link: "/docs/getting-started/lambda"},

‎src/docs/components/otlp-exporter.mdx

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -321,25 +321,38 @@ To send trace data, all you need is the API key for your Environment:
321321
```yaml lineNumbers=true highlight={7,9}
322322
# Honeycomb Collector configuration
323323
exporters:
324-
otlp:
324+
otlp/traces:
325325
endpoint: api.honeycomb.io:443
326326
headers:
327327
# You can find your Honeycomb API key under Environment settings
328328
"x-honeycomb-team":"<YOUR_API_KEY>"
329+
service:
330+
extensions: []
331+
pipelines:
332+
traces:
333+
receivers: [otlp]
334+
processors: []
335+
exporters: [otlp/traces]
329336
```
330337

331-
332338
To send metrics data, you also need to specify the dataset for metrics data:
333339

334340
```yaml lineNumbers=true highlight={7,9}
335341
# Honeycomb Collector configuration
336342
exporters:
337-
otlp:
343+
otlp/metrics:
338344
endpoint: api.honeycomb.io:443
339345
headers:
340346
# You can find your Honeycomb API key under Environment settings
341347
"x-honeycomb-team":"<YOUR_API_KEY>"
342348
"x-honeycomb-dataset": "<YOUR_METRICS_DATASET>"
349+
service:
350+
extensions: []
351+
pipelines:
352+
metrics:
353+
receivers: [otlp]
354+
processors: []
355+
exporters: [otlp/metrics]
343356
```
344357

345358
See [Honeycomb's OpenTelemetry Collector](https://docs.honeycomb.io/getting-data-in/otel-collector/) docs to learn about additional configuration options.

‎src/docs/getting-started/php-sdk.mdx

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: 'Getting Started with the PHP SDK on Traces Instrumentation'
3+
description:
4+
OpenTelemetry provides different language SDKs to instrument code for collecting telemetry data in the application.
5+
In this tutorial, we will introduce how to use OpenTelemetry PHP SDK for traces instrumentation in the application...
6+
path: '/docs/getting-started/php-sdk'
7+
---
8+
9+
import SectionSeparator from "components/MdxSectionSeparator/sectionSeparator.jsx"
10+
11+
OpenTelemetry provides different language SDKs to instrument code for collecting telemetry data in the application.
12+
13+
In this tutorial, we will introduce how to use [OpenTelemetry PHP SDK](https://github.com/open-telemetry/opentelemetry-php) for manual instrumentation on traces in the applications.
14+
15+
<SectionSeparator />
16+
17+
## Getting Started
18+
19+
* [Manual Instrumentation on Traces with PHP SDK](/docs/getting-started/php-sdk/trace-manual-instr)
20+
21+
22+
## Sample Code with PHP SDK
23+
* [AWS Distro for OpenTelemetry Sample Code with PHP SDK](https://github.com/aws-observability/aws-otel-php/tree/main/SampleApp)

‎src/docs/getting-started/php-sdk/trace-manual-instr.mdx

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
title: 'Tracing with the AWS Distro for OpenTelemetry PHP SDK and X-Ray'
3+
description: Learn how to get started with PHP SDK for adding tracing to applications and libraries.
4+
path: '/docs/getting-started/php-sdk/trace-manual-instr'
5+
---
6+
7+
import SectionSeparator from "components/MdxSectionSeparator/sectionSeparator.jsx"
8+
import SubSectionSeparator from "components/MdxSubSectionSeparator/subsectionSeparator.jsx"
9+
10+
<SectionSeparator />
11+
12+
13+
## Introduction
14+
15+
This guide covers the components of the AWS Distro for OpenTelemetry (ADOT) PHP, and describes how to configure the relevant ADOT components to send trace data to the AWS X-Ray backend.
16+
17+
For more information on OpenTelemetry PHP, see the [OpenTelemetry Developer Guide for PHP](https://opentelemetry.io/docs/instrumentation/php/)
18+
19+
<SectionSeparator />
20+
21+
## Requirements
22+
23+
[PHP 7.4 or later](https://www.php.net/downloads.php) is required to run an application using OpenTelemetry
24+
25+
Note: You’ll also need to have the [ADOT Collector](https://aws-otel.github.io/docs/getting-started/collector) running to export traces to X-Ray.
26+
27+
<SectionSeparator />
28+
29+
## Installation
30+
31+
In order to send traces from your application, the following OpenTelemetry PHP packages must be installed in your application’s root directory
32+
33+
34+
* [X-Ray ID Generator](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/src/Aws/Xray)
35+
* [X-Ray propagator](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/src/Aws/Xray)
36+
37+
```bash
38+
composer require open-telemetry/contrib-aws
39+
```
40+
41+
* [OpenTelemetry API for tracing](https://packagist.org/packages/open-telemetry/api)
42+
43+
```bash
44+
composer require open-telemetry/api
45+
```
46+
47+
* [OpenTelemetry SDK for tracing](https://packagist.org/packages/open-telemetry/sdk)
48+
49+
```bash
50+
composer require open-telemetry/sdk
51+
```
52+
53+
54+
* [OTLP GRPC exporter](https://packagist.org/packages/open-telemetry/exporter-otlp-grpc)
55+
56+
In order to use this package, you must also install the GRPC package using PECL. See the instructions on the [OpenTelemetry PHP repository](https://github.com/open-telemetry/opentelemetry-php#optional-dependencies) for more information.
57+
58+
```bash
59+
composer require open-telemetry/exporter-otlp-grpc
60+
```
61+
62+
<SectionSeparator />
63+
64+
65+
## Setting up the Global Tracer
66+
67+
### Sending Traces to AWS X-Ray
68+
69+
In order to send trace data to AWS X-Ray, instantiate a new tracer provider and provide it with the X-Ray ID generator, X-Ray propagator, and OTLP exporter pointing to the collector's address.
70+
71+
```
72+
// Initialize Span Processor, X-Ray ID generator, Tracer Provider, and Propagator
73+
74+
$spanProcessor = new SimpleSpanProcessor(new OTLPExporter());
75+
$idGenerator = new IdGenerator();
76+
$tracerProvider = new TracerProvider($spanProcessor, null, null, null, $idGenerator);
77+
$propagator = new Propagator();
78+
$tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');
79+
```
80+
81+
<SubSectionSeparator />
82+
83+
### Using the AWS resource detectors
84+
85+
The AWS resource detectors are included with the X-Ray ID generator and X-Ray propagator in the `open-telemetry/contrib-aws` package.
86+
87+
The ADOT PHP SDK supports automatically recording metadata in EC2, Elastic Beanstalk, ECS, and EKS environments.
88+
89+
90+
```
91+
use GuzzleHttp\Client;
92+
use GuzzleHttp\Psr7\HttpFactory;
93+
use OpenTelemetry\Aws\Ec2\Detector;
94+
95+
$client = new Client();
96+
$requestFactory = new HttpFactory();
97+
98+
$detector = new Detector($client, $requestFactory);
99+
100+
$tracerProvider = new TracerProvider($spanProcessor, null, $detector->getResource(), null, $idGenerator);
101+
102+
```
103+
104+
105+
To see what attributes are captured and how to add other resource detectors, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/src/Aws).
106+
107+
<SubSectionSeparator />
108+
109+
### Debug Logging
110+
111+
To enable debug logging for the OpenTelemetry SDK, create a logger as follows:
112+
113+
```
114+
use Monolog\Handler\StreamHandler;
115+
use Monolog\Logger;
116+
use OpenTelemetry\SDK\Common\Log\LoggerHolder;
117+
use Psr\Log\LogLevel;
118+
119+
LoggerHolder::set(
120+
new Logger('otel-php', [new StreamHandler(STDOUT, LogLevel::DEBUG)])
121+
);
122+
```
123+
124+
<SubSectionSeparator />
125+
126+
## Instrumenting an Application
127+
128+
**Warning: Some instrumentations are not yet stable and the attributes they collect are subject to change until the instrumentation reaches 1.0 stability. It is recommended that you pin a specific version of an instrumentation**
129+
130+
When you instrument a library, every time the library is used, the request is automatically wrapped with a populated span.
131+
132+
133+
134+
### Instrumenting the AWS SDK
135+
136+
Run the following command to import the AWS SDK Instrumentation:
137+
138+
139+
```
140+
composer require open-telemetry/opentelemetry-php-contrib:0.0.15
141+
```
142+
143+
144+
Import the `AwsSdkInstrumentation` class in your PHP source code to activate the SDK instrumentation:
145+
146+
147+
```
148+
use OpenTelemetry\Instrumentation\AwsSdk\AwsSdkInstrumentation;
149+
```
150+
151+
152+
Tracing support for downstream AWS SDK calls to Amazon DynamoDB, S3, and others is provided by the [OpenTelemetry PHP AWS SDK Instrumentation](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/src/Instrumentation/AwsSdk). The example below demonstrates setting up the AWS SDK instrumentation and tracing a call to S3.
153+
154+
155+
```
156+
use OpenTelemetry\Instrumentation\AwsSdk\AwsSdkInstrumentation;
157+
158+
// Initialize Span Processor, X-Ray ID generator, Tracer Provider, and Propagator
159+
$spanProcessor = new SimpleSpanProcessor(new OTLPExporter());
160+
$xrayIdGenerator = new IdGenerator();
161+
$tracerProvider = new TracerProvider($spanProcessor, null, null, null, $xrayIdGenerator);
162+
$xrayPropagator = new Propagator();
163+
164+
// Create new instance of AWS SDK Instrumentation class
165+
$awssdkinstrumentation = new AwsSdkInstrumentation();
166+
167+
// Configure AWS SDK Instrumentation with Propagator and set Tracer Provider (created above)
168+
$awssdkinstrumentation->setPropagator($xrayPropagator);
169+
$awssdkinstrumentation->setTracerProvider($tracerProvider);
170+
171+
// Create and activate root span
172+
$root = $awssdkinstrumentation->getTracer()->spanBuilder('AwsSDKInstrumentation')->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
173+
$rootScope = $root->activate();
174+
175+
// Initialize all AWS Client instances
176+
$s3Client = new S3Client([
177+
'region' => 'us-west-2',
178+
]);
179+
180+
// Pass client instances to AWS SDK
181+
$awssdkinstrumentation->instrumentClients([$s3Client]);
182+
183+
// Activate Instrumentation -- all AWS Client calls will be automatically instrumented
184+
$awssdkinstrumentation->activate();
185+
186+
// Make S3 client call
187+
$result = $s3Client->listBuckets();
188+
189+
// End the root span after all the calls to the AWS SDK have been made
190+
$root->end();
191+
$rootScope->detach();
192+
```
193+
194+
<SectionSeparator />
195+
196+
## Custom Instrumentation
197+
198+
### Creating Custom Spans
199+
200+
Use custom spans to monitor the performance of internal activities that are not captured by instrumentation libraries. Note that only spans of kind `Server` are converted into X-Ray segments. All other spans are converted into X-Ray subsegments. For more on segments and subsegments, see the [AWS X-Ray developer guide](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments).
201+
202+
203+
```
204+
// this span will be translated to a segment in X-Ray backend
205+
$span = $awssdkinstrumentation->getTracer()->spanBuilder('segment')->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
206+
207+
// this span will be translated to a subsegment in X-Ray backend
208+
$span2 = $awssdkinstrumentation->getTracer()->spanBuilder('subsegment')->setSpanKind(SpanKind::KIND_CLIENT)->startSpan();
209+
```
210+
211+
212+
213+
### Adding custom attributes
214+
215+
You can also add custom key-value pairs as attributes to your spans. Attributes are converted to metadata by default. If you [configure your collector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/7bf2266a025425993a233f66c77a0810ab11a78b/exporter/awsxrayexporter#exporter-configuration), you can convert some or all of the attributes to annotations. To read more about X-Ray annotations and metadata see the [AWS X-Ray Developer Guide](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations).
216+
217+
218+
```
219+
$span = $tracer
220+
->spanBuilder('span')
221+
->startSpan();
222+
223+
$spanScope = $root->activate();
224+
225+
$span->setAttributes(["a" => "1"]);
226+
227+
$span->end();
228+
$spanScope->detach();
229+
```
230+
231+
<SectionSeparator />
232+
233+
234+
## Sample Application
235+
236+
See the [AWS Distro for OpenTelemetry Sample Code with PHP SDK](https://github.com/aws-observability/aws-otel-php) for instructions on setting up and using the sample application.
237+
238+

‎src/docs/getting-started/x-ray.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -240,15 +240,15 @@ exporters:
240240
awsxray:
241241
242242
processors:
243-
memorylimiter:
243+
memory_limiter:
244244
limit_mib: 100
245245
check_interval: 5s
246246
247247
service:
248248
pipelines:
249249
traces:
250250
processors:
251-
- memorylimiter
251+
- memory_limiter
252252
receivers:
253253
- otlp
254254
exporters:

‎src/docs/index.mdx

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Welcome
3+
description: Welcome to the technical documentation for AWS distro for OpenTelemetry
4+
path: '/docs'
5+
---
6+
7+
Welcome to the technical documentation for AWS Distro for OpenTelemetry.
8+
9+
We suggest that you start with the [Introduction](/docs/introduction).

‎src/docs/setup/ec2.mdx

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,9 @@ To install AWSDistroOTel-Collector package on EC2 instances of Auto Scaling grou
128128
<img src={imgSSM8} alt="Diagram" style="margin: 30px 0;" />
129129

130130
**Notes**
131+
132+
The SSM distributor creates an environment file at ```/opt/aws/aws-otel-collector/etc/.env``` . Any environment variable that will be used in the [open telemetry configuration](https://opentelemetry.io/docs/collector/configuration/#configuration-environment-variables) needs to be added to this file.
133+
131134
After you finished the tutorial, remember to shut down the new EC2 instance we created in the tutorial in order to avoid additional charges.
132135

133136

0 commit comments

Comments
 (0)