Skip to content

Commit d94be54

Browse files
pglombardopglombardo
committed
Updated repo docs.
1 parent abac9cb commit d94be54

File tree

2 files changed

+103
-90
lines changed

2 files changed

+103
-90
lines changed

‎INSTALLATION.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Automated
2+
3+
The Instana package sensor can be enabled without any code modifications. To do this, set the following environment variable for your Python application:
4+
5+
AUTOWRAPT_BOOTSTRAP=runtime
6+
7+
This will cause the Instana Python package to automatically instrument your Python application. Once it finds the host agent, it will begin to report Python metrics.
8+
9+
# Manual
10+
11+
In any Python 2.7 or great application, to manually enable the Instana sensor, simply import the package:
12+
13+
import instana
14+
15+
This will initialize the package and it will begin to report key Python metrics.
16+
17+
# Django (Automated)
18+
19+
The Instana package offers a method to automatically instrument your Django application without any code changes required. To enable the Django instrumetation, set the environment variable `AUTOWRAPT_BOOTSTRAP=django` (use `django19` for Django version 1.9.x) for your Python application.
20+
21+
# Django (Manual Installation)
22+
23+
To instead manually install the Instana Django middleware into your Django application, import the package and add `instana.django.InstanaMiddleware` to the top of your `MIDDLEWARE` (or `MIDDLEWARE_CLASSES` for earlier versions) in your `settings.py`:
24+
25+
```Python
26+
import instana
27+
28+
MIDDLEWARE = [
29+
'instana.django.InstanaMiddleware',
30+
# ...
31+
'django.contrib.messages.middleware.MessageMiddleware',
32+
'django.middleware.clickjacking.XFrameOptionsMiddleware',
33+
]
34+
```
35+
36+
# Flask
37+
38+
To enable the Flask instrumentation, set the following environment variable in your _application boot environment_ and then restart your application:
39+
40+
`export AUTOWRAPT_BOOTSTRAP=flask`
41+
42+
# WSGI Stacks
43+
44+
The Instana sensor bundles with it WSGI middleware. The usage of this middleware is automated for various frameworks but for those that arent' supported yet, see the [WSGI documentation](WSGI.md) for details on how to manually add it to your stack.
45+
46+
# uWSGI
47+
48+
## Threads
49+
50+
This Python instrumentation spawns a lightweight background thread to periodically collect and report process metrics. By default, the GIL and threading is disabled under uWSGI. If you wish to instrument your application running under uWSGI, make sure that you enable threads by passing `--enable-threads` (or `enable-threads = true` in ini style). More details in the [uWSGI documentation](https://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html#a-note-on-python-threads).
51+
52+
## Forking off Workers
53+
54+
If you use uWSGI in forking workers mode, you must specify `--lazy-apps` (or `lazy-apps = true` in ini style) to load the application in the worker instead of the master process.
55+
56+
## uWSGI Example: Command-line
57+
58+
```sh
59+
uwsgi --socket 0.0.0.0:5000 --protocol=http -w wsgi -p 4 --enable-threads --lazy-apps
60+
```
61+
62+
## uWSGI Example: ini file
63+
64+
```ini
65+
[uwsgi]
66+
http = :5000
67+
master = true
68+
processes = 4
69+
enable-threads = true # required
70+
lazy-apps = true # if using "processes", set lazy-apps to true
71+
72+
# Set the Instana sensor environment variable here
73+
env = AUTOWRAPT_BOOTSTRAP=flask
74+
```
75+
# Want End User Monitoring?
76+
77+
Instana provides deep end user monitoring that links server side traces with browser events to give you a complete view from server to browser.
78+
79+
For Python templates and views, get your EUM API key from your Instana dashboard and you can call `instana.helpers.eum_snippet(api_key='abc')` from within your layout file. This will output
80+
a small javascript snippet of code to instrument browser events. It's based on [Weasel](https://github.com/instana/weasel). Check it out.
81+
82+
As an example, you could do the following:
83+
84+
```python
85+
from instana.helpers import eum_snippet
86+
87+
instana.api_key = 'abc'
88+
meta_kvs = { 'username': user.name }
89+
90+
# This will return a string containing the EUM javascript for the layout or view.
91+
eum_snippet(meta=meta_kvs)
92+
```
93+
94+
The optional second argument to `eum_snippet()` is a hash of metadata key/values that will be reported along with the browser instrumentation.
95+
96+
![Instana EUM example with metadata](https://s3.amazonaws.com/instana/Instana+Gameface+EUM+with+metadata+2016-12-22+at+15.32.01.png)
97+
98+
See also the [End User Monitoring](https://docs.instana.io/products/website_monitoring/#configuration) in the Instana documentation portal.

‎README.md‎

Lines changed: 5 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -6,105 +6,20 @@
66

77
The instana package provides Python metrics and traces (request, queue & cross-host) for [Instana](https://www.instana.com/).
88

9-
[![Build Status](https://travis-ci.org/instana/python-sensor.svg?branch=master)](https://travis-ci.org/instana/python-sensor)
10-
[![OpenTracing Badge](https://img.shields.io/badge/OpenTracing-enabled-blue.svg)](http://opentracing.io)
11-
12-
## Note
13-
149
This package supports Python 2.7 or greater.
1510

1611
Any and all feedback is welcome. Happy Python visibility.
1712

18-
## Installation
19-
20-
`pip install instana` into the virtual-env or container ([hosted on pypi](https://pypi.python.org/pypi/instana))
21-
22-
## Django
23-
24-
For Django versions >= 1.10 set the following environment variable in your _application boot environment_ and then restart your application:
25-
26-
`export AUTOWRAPT_BOOTSTRAP=django`
27-
28-
For Django version 1.9.x, instead set:
29-
30-
`export AUTOWRAPT_BOOTSTRAP=django19`
31-
32-
## Flask
33-
34-
To enable the Flask instrumentation, set the following environment variable in your _application boot environment_ and then restart your application:
35-
36-
`export AUTOWRAPT_BOOTSTRAP=flask`
37-
38-
## WSGI Compliant Stacks
39-
40-
The Instana sensor bundles with it WSGI middleware. The usage of this middleware is automated for various frameworks but for those that arent' supported yet, see the [WSGI documentation](WSGI.md) for details on how to manually add it to your stack.
41-
42-
## Runtime Monitoring Only
43-
44-
_Note: When the Django or Flask instrumentation is used, runtime monitoring is automatically included. Use this section if you only want to see runtime metrics._
45-
46-
To enable runtime monitoring (without request tracing), set the following environment variable in your _application boot environment_ and then restart your application:
47-
48-
`export AUTOWRAPT_BOOTSTRAP=runtime`
49-
50-
## uWSGI
51-
52-
### Threads
53-
54-
This Python instrumentation spawns a lightweight background thread to periodically collect and report process metrics. By default, the GIL and threading is disabled under uWSGI. If you wish to instrument your application running under uWSGI, make sure that you enable threads by passing `--enable-threads` (or `enable-threads = true` in ini style). More details in the [uWSGI documentation](https://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html#a-note-on-python-threads).
55-
56-
### Forking off Workers
57-
58-
If you use uWSGI in forking workers mode, you must specify `--lazy-apps` (or `lazy-apps = true` in ini style) to load the application in the worker instead of the master process.
59-
60-
### uWSGI Example: Command-line
61-
62-
```sh
63-
uwsgi --socket 0.0.0.0:5000 --protocol=http -w wsgi -p 4 --enable-threads --lazy-apps
64-
```
65-
66-
### uWSGI Example: ini file
67-
68-
```ini
69-
[uwsgi]
70-
http = :5000
71-
master = true
72-
processes = 4
73-
enable-threads = true # required
74-
lazy-apps = true # if using "processes", set lazy-apps to true
75-
76-
# Set the Instana sensor environment variable here
77-
env = AUTOWRAPT_BOOTSTRAP=flask
78-
```
13+
[![Build Status](https://travis-ci.org/instana/python-sensor.svg?branch=master)](https://travis-ci.org/instana/python-sensor)
14+
[![OpenTracing Badge](https://img.shields.io/badge/OpenTracing-enabled-blue.svg)](http://opentracing.io)
7915

80-
## Usage
16+
## Usage & Installation
8117

8218
The instana package will automatically collect key metrics from your Python processes. Just install and go.
8319

84-
## Want End User Monitoring?
85-
86-
Instana provides deep end user monitoring that links server side traces with browser events to give you a complete view from server to browser.
87-
88-
For Python templates and views, get your EUM API key from your Instana dashboard and you can call `instana.helpers.eum_snippet(api_key='abc')` from within your layout file. This will output
89-
a small javascript snippet of code to instrument browser events. It's based on [Weasel](https://github.com/instana/weasel). Check it out.
90-
91-
As an example, you could do the following:
92-
93-
```python
94-
from instana.helpers import eum_snippet
95-
96-
instana.api_key = 'abc'
97-
meta_kvs = { 'username': user.name }
98-
99-
# This will return a string containing the EUM javascript for the layout or view.
100-
eum_snippet(meta=meta_kvs)
101-
```
102-
103-
The optional second argument to `eum_snippet()` is a hash of metadata key/values that will be reported along with the browser instrumentation.
104-
105-
![Instana EUM example with metadata](https://s3.amazonaws.com/instana/Instana+Gameface+EUM+with+metadata+2016-12-22+at+15.32.01.png)
20+
`pip install instana` into the virtual-env or container ([hosted on pypi](https://pypi.python.org/pypi/instana))
10621

107-
See also the [End User Monitoring](https://docs.instana.io/products/website_monitoring/#configuration) in the Instana documentation portal.
22+
See our detailed [Installation document](INSTALLATION.md) for environment specific information covering Django, Flask, End-user Monitoring (EUM) and more.
10823

10924
## OpenTracing
11025

0 commit comments

Comments
 (0)