Skip to content
This repository was archived by the owner on Jan 3, 2023. It is now read-only.

Commit 325686a

Browse files
galpizarsfxmmusik
galpizarsfx
and
mmusik
authored
1017 python aws (#32)
* Update README.rst * Update README.rst * Update README.rst * Update README.rst Updating installation instructions * Update README.rst Updating python wrapper installation instructions * Change the order of options, cleanup the instructions for SIGNALFX_INGEST_ENDPOINT * Update README.rst Revised step 2 and 3 * Update README.rst Placed metrics information to the bottom of the document * Update README.rst Updating based on feedback from Marta * Update README.rst Made various updates, including in step 3: Set environment variables * Update README.rst Made updates based on feedback from Mark. Most importantly, I rearranged the options: - Previous Option 1, is now Option 3. - Previous Option 2, is now Option 1 - Previous Option 3, is now Option 2 * Update README.rst Making style changes * Update README.rst Making minor style changes * Update README.rst python ==> Python * Update README.rst lambda ==> Lambda * Update README.rst Updated "step 3" to include the different options for updating environment variables. * Update README.rst variable ==> variables * Update README.rst Added 2020, and added "include the following code in your function:" * updated copyrights for splunk * correct form of a copyright Co-authored-by: Marta Musik <[email protected]>
1 parent a6bf942 commit 325686a

File tree

1 file changed

+154
-96
lines changed

1 file changed

+154
-96
lines changed

‎README.rst

Lines changed: 154 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,134 @@
11
SignalFx Python Lambda Wrapper
2-
==============================
3-
4-
SignalFx Python Lambda Wrapper.
5-
6-
Usage
7-
-----
8-
9-
The SignalFx Python Lambda Wrapper is a wrapper around an AWS Lambda
10-
Python function handler, used to instrument execution of the function
11-
and send metrics and traces to SignalFx.
12-
13-
Installation
14-
~~~~~~~~~~~~
15-
16-
To install from PyPi
2+
===============================
3+
4+
Overview
5+
---------
6+
7+
You can use this document to add a SignalFx wrapper to your AWS Lambda for Python. 
8+
9+
The SignalFx Python Lambda Wrapper wraps around an AWS Lambda Python function handler, which allows metrics and traces to be sent to SignalFx.
10+
11+
At a high-level, to add a SignalFx Python Lambda wrapper, you can package the code yourself, or you can use a Lambda layer containing the wrapper and then attach the layer to a Lambda function.
12+
13+
To learn more about Lambda Layers, please visit the AWS documentation site and see [AWS Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html).
14+
15+
Step 1: Add the Lambda wrapper in AWS
16+
-----------------------------------------
17+
18+
To add the SignalFx wrapper, you have the following options:
19+
20+
* Option 1: In AWS, create a Lambda function, then attach a SignalFx-hosted layer with a wrapper.
21+
* If you are already using Lambda layers, then SignalFx recommends that you follow this option.
22+
* In this option, you will use a Lambda layer created and hosted by SignalFx.
23+
* Option 2: In AWS, create a Lambda function, then create and attach a layer based on a SignalFx SAM (Serverless Application Model) template.
24+
* If you are already using Lambda layers, then SignalFx also recommends that you follow this option.
25+
* In this option, you will choose a SignalFx template, and then deploy a copy of the layer.
26+
* Option 3: Use the wrapper as a regular dependency, and then create a Lambda function based on your artifact containing both code and dependencies.
27+
28+
Option 1: Create a Lambda function, then attach the SignalFx-hosted Lambda layer
29+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30+
31+
In this option, you will use a Lambda layer created and hosted by SignalFx.
32+
33+
1. To verify compatibility, review the list of supported regions. See [Lambda Layer Versions](https://github.com/signalfx/lambda-layer-versions/blob/master/python/PYTHON.md).
34+
2. Open your AWS console. 
35+
3. In the landing page, under **Compute**, click **Lambda**.
36+
4. Click **Create function** to create a layer with SignalFx's capabilities.
37+
5. Click **Author from scratch**.
38+
6. In **Function name**, enter a descriptive name for the wrapper. 
39+
7. In **Runtime**, select the desired language.
40+
8. Click **Create function**. 
41+
9. Click on **Layers**, then add a layer.
42+
10. Mark **Provide a layer version**.
43+
11. Enter an ARN number.
44+
* To locate the ARN number, see [Lambda Layer Versions](https://github.com/signalfx/lambda-layer-versions/blob/master/python/PYTHON.md).
45+
46+
Option 2: Create a Lambda function, then create and attach a layer based on a SignalFx template
47+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
48+
49+
In this option, you will choose a SignalFx template, and then deploy a copy of the layer.
50+
51+
1. Open your AWS console. 
52+
2. In the landing page, under **Compute**, click **Lambda**.
53+
3. Click **Create function** to create a layer with SignalFx's capabilities.
54+
4. Click **Browse serverless app repository**.
55+
5. Click **Public applications**.
56+
6. In the search field, enter and select **signalfx-lambda-python-wrapper**.
57+
7. Review the template, permissions, licenses, and then click **Deploy**.
58+
* A copy of the layer will now be deployed into your account.
59+
8. Return to the previous screen to add a layer to the function, select from list of runtime compatible layers, and then select the name of the copy. 
60+
61+
Option 3: Install the wrapper package with pip
62+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
63+
64+
Run the following installation script in your command line:
1765

1866
.. code::
1967
2068
pip install signalfx_lambda
2169
22-
Configuring the ingest endpoint
23-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2470
25-
By default, this function wrapper will send to the ``us0`` realm. If you are
26-
not in this realm you will need to set the ``SIGNALFX_INGEST_ENDPOINT`` environment
27-
variable to the correct realm ingest endpoint (``https://ingest.{REALM}.signalfx.com``).
28-
To determine what realm you are in, check your profile page in the SignalFx
29-
web application (click the avatar in the upper right and click My Profile).
71+
Step 2: Locate and set the ingest endpoint
72+
-------------------------------------------
73+
By default, this function wrapper will send data to the us0 realm. As a result, if you are not in us0 realm and you want to use the ingest endpoint directly, then you must explicitly set your realm. To set your realm, use a subdomain, such as ingest.us1.signalfx.com or ingest.eu0.signalfx.com.
3074

75+
To locate your realm:
3176

32-
Environment Variables
33-
~~~~~~~~~~~~~~~~~~~~~
77+
1. Open SignalFx and in the top, right corner, click your profile icon.
78+
2. Click **My Profile**.
79+
3. Next to **Organizations**, review the listed realm.
3480

35-
**Note: the environment variables ``SIGNALFX_INGEST_ENDPOINT`` and ``SIGNALFX_AUTH_TOKEN`` are being deprecated and will not be supported in future releases.**
3681

37-
.. code:: bash
38-
39-
SIGNALFX_ACCESS_TOKEN=access token
40-
41-
# endpoint for both metrics and tracer. Overridden by SIGNALFX_METRICS_URL
42-
# and SIGNALFX_TRACING_URL if set
43-
SIGNALFX_ENDPOINT_URL=http://<my_gateway>:8080
82+
Step 3: Set environment variables
83+
----------------------------------
4484

45-
# optional metrics and tracing configuration
85+
1. Set SIGNALFX_ACCESS_TOKEN with your correct access token. Review the following example.
4686

47-
SIGNALFX_METRICS_URL=ingest endpoint [ default: https://pops.signalfx.com ]
48-
SIGNALFX_SEND_TIMEOUT=timeout in seconds for sending datapoint [ default: 0.3 ]
87+
.. code:: bash
4988
50-
SIGNALFX_TRACING_URL=tracing endpoint [ default: https://ingest.signalfx.com/v1/trace ]
89+
SIGNALFX_ACCESS_TOKEN=access token
5190
52-
``SIGNALFX_ENDPOINT_URL`` can be used to configure a common endpoint for metrics and
53-
traces, as is the case when forwarding with the Smart Gateway. The path ``/v1/trace``
54-
will automatically be added to the endpoint for traces.
91+
2. If you use POPS, Smart Gateway, or want to ingest directly from a realm other than us0, then you must set at least one endpoint variable. (For environment variables, SignalFx defaults to the us0 realm. As a result, if you are not in the us0 realm, you may need to set your environment variables.) There are two options:
5592

56-
If either ``SIGNALFX_TRACING_URL`` or ``SIGNALFX_METRICS_URL`` are set, they will take
57-
precendence over ``SIGNALFX_ENDPOINT_URL`` for their respective components.
93+
**Option 1**
5894

59-
For example, if only ``SIGNALFX_ENDPOINT_URL`` is set:
95+
You can update ``SIGNALFX_ENDPOINT_URL`` where both metrics and traces will be sent to the gateway address. Note that the path ``/v1/trace`` will be automatically added to the endpoint for traces.
6096

6197
.. code:: bash
6298
6399
SIGNALFX_ENDPOINT_URL=http://<my_gateway>:8080
100+
64101
65-
Both metrics and traces will be sent to the gateway address.
102+
**Option 2**
66103

67-
If ``SIGNALFX_ENDPOINT_URL`` and ``SIGNALFX_METRICS_URL`` are set:
104+
You can update ``SIGNALFX_ENDPOINT_URL`` and ``SIGNALFX_METRICS_URL`` where traces will be sent to the gateway and metrics will go through POPS, respectively.
68105

69106
.. code:: bash
70107
71108
SIGNALFX_METRICS_URL=https://pops.signalfx.com
72109
SIGNALFX_ENDPOINT_URL=http://<my_gateway>:8080
110+
111+
To learn more, see:
112+
* [SignalFx Point of Presence Service (POPS)](https://docs.signalfx.com/en/latest/integrations/integrations-reference/integrations.signalfx.point.of.presence.service.(pops).html)
113+
* [Deploying the SignalFx Smart Gateway](https://docs.signalfx.com/en/latest/apm/apm-deployment/smart-gateway.html)
114+
115+
116+
3. (Optional) Set additional environment variables. Review the following examples.
117+
118+
.. code:: bash
73119
74-
Traces will be sent to the gateway and metrics will go through POPS.
120+
SIGNALFX_SEND_TIMEOUT=timeout in seconds for sending datapoint [ default: 0.3 ]
121+
SIGNALFX_TRACING_URL=tracing endpoint [ default: https://ingest.signalfx.com/v1/trace ]
122+
75123
76-
Wrapping a function
77-
~~~~~~~~~~~~~~~~~~~
124+
Step 4: Wrap a function
125+
--------------------------
78126

79127
There are two wrappers provided.
80128

81-
For metrics, decorate your handler with @signalfx_lambda.emits_metrics
129+
The decorators can be used individually or together.
130+
131+
1. For metrics, decorate your handler with **@signalfx_lambda.emits_metrics**. Review the following example.
82132

83133
.. code:: python
84134
@@ -88,7 +138,7 @@ For metrics, decorate your handler with @signalfx_lambda.emits_metrics
88138
def handler(event, context):
89139
# your code
90140
91-
For tracing, use the @signalfx_lambda.is_traced decorator
141+
2. For tracing, decorate your handler with **@signalfx_lambda.is_traced**. Review the following example.
92142

93143
.. code:: python
94144
@@ -98,10 +148,50 @@ For tracing, use the @signalfx_lambda.is_traced decorator
98148
def handler(event, context):
99149
# your code
100150
101-
The decorators can be used individually or together.
151+
152+
Step 5: Send custom metrics from a Lambda function
153+
-------------------------------------------------------
154+
155+
1. To send custom metrics from a Lambda function, include the following code in your function:
156+
157+
.. code:: python
158+
159+
import signalfx_lambda
160+
161+
# sending application_performance metric with value 100 and dimension abc:def
162+
signalfx_lambda.send_gauge('application_performance', 100, {'abc':'def'})
163+
164+
# sending counter metric with no dimension
165+
signalfx_lambda.send_counter('database_calls', 1)
166+
167+
168+
Step 6: Add tracing to the Lambda function
169+
-------------------------------------------
170+
171+
1. To trace critical parts of your handler function, include the following code in your function:
172+
173+
.. code:: python
174+
175+
import opentracing
176+
177+
tracer = opentracing.tracer
178+
179+
def some_function():
180+
with tracer.start_active_span("span_name", tags=tags) as scope:
181+
182+
# do some work
183+
184+
span = scope.span
185+
span.set_tag("example_tag", "example_value")
186+
187+
To review more examples and usage details, see [Jaeger Python Tracer](https://github.com/signalfx/jaeger-client-python>).
188+
189+
190+
Additional information
191+
------------------------
102192

103193
Metrics and dimensions sent by the metrics wrapper
104-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
105195

106196
The Lambda wrapper sends the following metrics to SignalFx:
107197

@@ -162,10 +252,10 @@ to SignalFx:
162252
| | ‘lambda_wrapper’ |
163253
+----------------------------------+----------------------------------+
164254

165-
Traces and tags sent by the Tracing wrapper
166-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167255

168-
The tracing wrapper creates a span for the wrapper handler. This span has the following tags:
256+
Tags sent by the tracing wrapper
257+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
258+
The tracing wrapper creates a span for the wrapper handler. This span contains the following tags:
169259

170260
+----------------------------------+----------------------------------+
171261
| Tag | Description |
@@ -203,46 +293,12 @@ The tracing wrapper creates a span for the wrapper handler. This span has the fo
203293
| | ‘python-lambda-wrapper’ |
204294
+----------------------------------+----------------------------------+
205295

206-
Sending custom metric from the Lambda function
207-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
208-
209-
.. code:: python
210-
211-
import signalfx_lambda
212-
213-
# sending application_performance metric with value 100 and dimension abc:def
214-
signalfx_lambda.send_gauge('application_performance', 100, {'abc':'def'})
215-
216-
# sending counter metric with no dimension
217-
signalfx_lambda.send_counter('database_calls', 1)
218-
219-
Adding manual tracing to the Lambda function
220-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221-
222-
Manual instrumentation can be added to trace critical parts of your handler
223-
function.
224-
225-
.. code:: python
226-
227-
import opentracing
228-
229-
tracer = opentracing.tracer
230296

231-
def some_function():
232-
with tracer.start_active_span("span_name", tags=tags) as scope:
233-
234-
# do some work
235-
236-
span = scope.span
237-
span.set_tag("example_tag", "example_value")
238-
239-
More examples and usage information can be found in the Jaeger Python Tracer
240-
`documentation <https://github.com/signalfx/jaeger-client-python>`_.
241297

242-
Testing it out locally
243-
~~~~~~~~~~~~~~~~~~~~~~
298+
Test locally
299+
^^^^^^^^^^^^^^^^^
300+
If you would like to test changes to a wrapper, run the following commands in your command line:
244301

245-
Use python-lambda-local
246302

247303
.. code::
248304
@@ -252,14 +308,16 @@ Use python-lambda-local
252308
253309
python-lambda-local tests/test.py tests/event.json -a 'arn:aws:lambda:us-east-1:accountId:function:functionNamePython:$LATEST'
254310
255-
Packaging
256-
~~~~~~~~~
311+
312+
Publish a new version
313+
^^^^^^^^^^^^^^^^^^^^^^^
314+
If you would like to publish a new version, run the following command in your command line to install a new Python package (build a wheel):
257315

258316
.. code::
259317
260318
python setup.py bdist_wheel --universal
261-
319+
262320
License
263-
~~~~~~~
321+
^^^^^^^^
322+
Apache Software License v2. Copyright © 2014-2020 Splunk, Inc.
264323

265-
Apache Software License v2. Copyright © 2014-2019 SignalFx

0 commit comments

Comments
 (0)