|
8 | 8 |
|
9 | 9 | [](https://travis-ci.com/getsentry/sentry-python)
|
10 | 10 |
|
11 |
| -***Sentry-Python is still under development and not yet documented*** For a |
12 |
| -stable SDK, use [raven](https://github.com/getsentry/raven-python). |
| 11 | +- [Documentation](https://docs.sentry.io/quickstart/?platform=python) |
13 | 12 |
|
14 |
| -## Getting started with the new Sentry SDK for Python |
| 13 | +# License |
15 | 14 |
|
16 |
| -Install this package with ``pip install sentry-sdk``. Then, in your code: |
17 |
| - |
18 |
| -```python |
19 |
| -import sentry_sdk |
20 |
| -sentry_sdk.init( dsn="https://[email protected]/123") |
21 |
| -``` |
22 |
| - |
23 |
| -After initialization, you can capture exceptions like this: |
24 |
| - |
25 |
| -```python |
26 |
| -sentry_sdk.capture_exception(ValueError()) |
27 |
| - |
28 |
| -try: |
29 |
| - raise ValueError() |
30 |
| -except Exception: |
31 |
| - sentry_sdk.capture_exception() |
32 |
| -``` |
33 |
| - |
34 |
| -...or send messages: |
35 |
| - |
36 |
| -```python |
37 |
| -sentry_sdk.capture_message("Hi Sentry!") |
38 |
| -``` |
39 |
| - |
40 |
| -## Scopes (contexts, tags) |
41 |
| - |
42 |
| -You can create a scope to attach data to all events happening inside of it: |
43 |
| - |
44 |
| -```python |
45 |
| -with sentry_sdk.Hub.current.push_scope(): |
46 |
| - with sentry_sdk.configure_scope() as scope: |
47 |
| - scope.transaction = "my_view_name" |
48 |
| - scope.set_tag("key", "value") |
49 |
| - scope.user = {"id": 123} |
50 |
| - |
51 |
| - # ValueError event will have all that data attached |
52 |
| - capture_exception(ValueError()) |
53 |
| - |
54 |
| -# This one not since it is outside of the context manager |
55 |
| -capture_exception(ValueError()) |
56 |
| -``` |
57 |
| - |
58 |
| -Scopes can be nested. If you call ``push_scope`` inside of the |
59 |
| -``with``-statement again, that scope will be pushed onto a stack. It will also |
60 |
| -inherit all data from the outer scope. |
61 |
| - |
62 |
| -### Scopes in unconfigured environments |
63 |
| - |
64 |
| -If you never call ``init``, no data will ever get sent to any server. In such |
65 |
| -situations, code like this is essentially deadweight: |
66 |
| - |
67 |
| -```python |
68 |
| -with sentry_sdk.configure_scope() as scope: |
69 |
| - scope.user = _get_user_data() |
70 |
| -``` |
71 |
| - |
72 |
| -Sentry-Python supports an alternative syntax for configuring a scope that |
73 |
| -solves this problem: |
74 |
| - |
75 |
| -```python |
76 |
| -@sentry_sdk.configure_scope |
77 |
| -def _(scope): |
78 |
| - scope.user = _get_user_data() |
79 |
| -``` |
80 |
| - |
81 |
| -Your function will just not be executed if there is no client configured. |
82 |
| - |
83 |
| -In your testing and development environment you still might want to run that |
84 |
| -code without sending any events. In that case, simply call ``init`` without a |
85 |
| -DSN: |
86 |
| - |
87 |
| -```python |
88 |
| -sentry_sdk.init() |
89 |
| -``` |
90 |
| - |
91 |
| -### Breadcrumbs |
92 |
| - |
93 |
| -Breadcrumbs also live on the stack. By default any (non-debug) log message |
94 |
| -anywhere in your system ends up as a breadcrumb, see [the logging |
95 |
| -docs](./docs/logging.md) for more information. You can, however, also create |
96 |
| -breadcrumbs manually: |
97 |
| - |
98 |
| -```python |
99 |
| -sentry_sdk.add_breadcrumb( |
100 |
| - timestamp=datetime.datetime.now(), |
101 |
| - type="log", |
102 |
| - level="debug", |
103 |
| - # message="hi", |
104 |
| - # category="myapp.models", |
105 |
| -}) |
106 |
| -``` |
107 |
| - |
108 |
| -You can also pass a callback to `add_breadcrumb` like so: |
109 |
| - |
110 |
| -```python |
111 |
| -sentry_sdk.add_breadcrumb(lambda: { |
112 |
| - "timestamp": datetime.datetime.now(), |
113 |
| - "type": "log", |
114 |
| - "level": "debug", |
115 |
| - # "message": "hi", |
116 |
| - # "category": "myapp.models", |
117 |
| -}) |
118 |
| -``` |
119 |
| - |
120 |
| -The callback will only be called if a sentry client is configured. |
121 |
| - |
122 |
| - |
123 |
| -## Concurrency |
124 |
| - |
125 |
| -* Sentry-Python currently does not support gevent-based setups. |
126 |
| -* On ``init``, Sentry-Python spawns a thread on its own. That means if you use |
127 |
| - ``uwsgi``, you currently need to enable threads. |
128 |
| -* On Python 3.7, Sentry-Python supports and automatically uses ``ContextVars``. |
129 |
| - This should effectively enable Sentry-Python to work with ``asyncio`` under |
130 |
| - that Python version. |
131 |
| - |
132 |
| - |
133 |
| -## PII |
134 |
| - |
135 |
| -Currently Sentry-Python does not send any personally-identifiable user data |
136 |
| -with events by default. You need to explicitly enable this behavior with the |
137 |
| -``send_default_pii`` option passed to ``init``: |
138 |
| - |
139 |
| -```python |
140 |
| -init(..., send_default_pii=True) |
141 |
| -``` |
142 |
| - |
143 |
| -## Integrations |
144 |
| - |
145 |
| -Head over to [the other pages](https://github.com/getsentry/sentry-python/tree/master/docs) |
146 |
| -to check out integrations, which use these low-level APIs so you don't have to. |
| 15 | +Licensed under the MIT, see `LICENSE` |
0 commit comments