diff options
| author | Armin Ronacher <armin.ronacher@active-4.com> | 2018-08-27 23:18:38 +0200 |
|---|---|---|
| committer | Armin Ronacher <armin.ronacher@active-4.com> | 2018-08-27 23:18:38 +0200 |
| commit | ea000f57b6f249974293003e97b84741323fadf5 (patch) | |
| tree | f2c05e5a3ea6086df2eb06d50e3f09af31cf4601 | |
| parent | f6d79c3bcc25e804b6259fa9c4a6e030f9033bb2 (diff) | |
| download | raven-ea000f57b6f249974293003e97b84741323fadf5.tar.gz | |
ref: Kill docs in repo
40 files changed, 6 insertions, 3774 deletions
diff --git a/.gitmodules b/.gitmodules index 12c98df..e69de29 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "docs/_sentryext"] - path = docs/_sentryext - url = https://github.com/getsentry/sentry-doc-support.git @@ -1,15 +1,10 @@ .. raw:: html <p align="center"> - -.. image:: docs/_static/logo.png - :target: https://sentry.io - :align: center - :width: 116 - :alt: Sentry website - -.. raw:: html - + <a href="https://sentry.io" target="_blank" align="center"> + <img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280"> + </a> + <br> </p> Raven - Sentry for Python diff --git a/codecov.yml b/codecov.yml index 5a43248..713ab60 100644 --- a/codecov.yml +++ b/codecov.yml @@ -9,6 +9,5 @@ coverage: ignore: - hooks/.* - ci/.* - - docs/.* comment: false diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 1db8f3c..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,130 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = ./_build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Sentry.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Sentry.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Sentry" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Sentry" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/_sentryext b/docs/_sentryext deleted file mode 160000 -Subproject ace38d37571b53dcbf6c00128b216fd9b53ec2b diff --git a/docs/_static/logo.png b/docs/_static/logo.png Binary files differdeleted file mode 100644 index 0275245..0000000 --- a/docs/_static/logo.png +++ /dev/null diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html deleted file mode 100644 index bf0b3c7..0000000 --- a/docs/_themes/kr/layout.html +++ /dev/null @@ -1,16 +0,0 @@ -{%- extends "basic/layout.html" %} -{%- block extrahead %} - {{ super() }} - {% if theme_touch_icon %} - <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" /> - {% endif %} - <link media="only screen and (max-device-width: 480px)" href="{{ - pathto('_static/small_flask.css', 1) }}" type= "text/css" rel="stylesheet" /> - <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9"> -{% endblock %} -{%- block relbar2 %}{% endblock %} -{%- block footer %} - <div class="footer"> - © Copyright {{ copyright }}. - </div> -{%- endblock %} diff --git a/docs/_themes/kr/relations.html b/docs/_themes/kr/relations.html deleted file mode 100644 index 3bbcde8..0000000 --- a/docs/_themes/kr/relations.html +++ /dev/null @@ -1,19 +0,0 @@ -<h3>Related Topics</h3> -<ul> - <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul> - {%- for parent in parents %} - <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul> - {%- endfor %} - {%- if prev %} - <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter') - }}">{{ prev.title }}</a></li> - {%- endif %} - {%- if next %} - <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter') - }}">{{ next.title }}</a></li> - {%- endif %} - {%- for parent in parents %} - </ul></li> - {%- endfor %} - </ul></li> -</ul> diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t deleted file mode 100644 index 3ca0fdd..0000000 --- a/docs/_themes/kr/static/flasky.css_t +++ /dev/null @@ -1,449 +0,0 @@ -/* - * flasky.css_t - * ~~~~~~~~~~~~ - * - * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. - * :license: Flask Design License, see LICENSE for details. - */ - -{% set page_width = '940px' %} -{% set sidebar_width = '220px' %} - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -img { - max-width: 100%; -} - -body { - font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; - font-size: 17px; - background-color: white; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - width: {{ page_width }}; - margin: 30px auto 0 auto; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 {{ sidebar_width }}; -} - -div.sphinxsidebar { - width: {{ sidebar_width }}; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 0 30px; -} - -img.floatingflask { - padding: 0 0 10px 10px; - float: right; -} - -div.footer { - width: {{ page_width }}; - margin: 20px auto 30px auto; - font-size: 14px; - color: #888; - text-align: right; -} - -div.footer a { - color: #888; -} - -div.related { - display: none; -} - -div.sphinxsidebar a { - color: #444; - text-decoration: none; - border-bottom: 1px dotted #999; -} - -div.sphinxsidebar a:hover { - border-bottom: 1px solid #999; -} - -div.sphinxsidebar { - font-size: 14px; - line-height: 1.5; -} - -div.sphinxsidebarwrapper { - padding: 18px 10px; -} - -div.sphinxsidebarwrapper p.logo { - padding: 0; - margin: -10px 0 0 -20px; - text-align: center; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - font-family: 'Garamond', 'Georgia', serif; - color: #444; - font-size: 24px; - font-weight: normal; - margin: 0 0 5px 0; - padding: 0; -} - -div.sphinxsidebar h4 { - font-size: 20px; -} - -div.sphinxsidebar h3 a { - color: #444; -} - -div.sphinxsidebar p.logo a, -div.sphinxsidebar h3 a, -div.sphinxsidebar p.logo a:hover, -div.sphinxsidebar h3 a:hover { - border: none; -} - -div.sphinxsidebar p { - color: #555; - margin: 10px 0; -} - -div.sphinxsidebar ul { - margin: 10px 0; - padding: 0; - color: #000; -} - -div.sphinxsidebar input { - border: 1px solid #ccc; - font-family: 'Georgia', serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #ddd; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #eaeaea; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - background: #fafafa; - margin: 20px -30px; - padding: 10px 30px; - border-top: 1px solid #ccc; - border-bottom: 1px solid #ccc; -} - -div.admonition tt.xref, div.admonition a tt { - border-bottom: 1px solid #fafafa; -} - -dd div.admonition { - margin-left: -60px; - padding-left: 60px; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight { - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.9em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #eee; - background: #fdfdfd; - font-size: 0.9em; -} - -table.footnote + table.footnote { - margin-top: -15px; - border-top: none; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td.label { - width: 0px; - padding: 0.3em 0 0.3em 0.5em; -} - -table.footnote td { - padding: 0.3em 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -blockquote { - margin: 0 0 0 30px; - padding: 0; -} - -ul, ol { - margin: 10px 0 10px 30px; - padding: 0; -} - -pre { - background: #eee; - padding: 7px 30px; - margin: 15px -30px; - line-height: 1.3em; -} - -dl pre, blockquote pre, li pre { - margin-left: -60px; - padding-left: 60px; -} - -dl dl pre { - margin-left: -90px; - padding-left: 90px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; - border-bottom: 1px solid white; -} - -a.reference { - text-decoration: none; - border-bottom: 1px dotted #004B6B; -} - -a.reference:hover { - border-bottom: 1px solid #6D4100; -} - -a.footnote-reference { - text-decoration: none; - font-size: 0.7em; - vertical-align: top; - border-bottom: 1px dotted #004B6B; -} - -a.footnote-reference:hover { - border-bottom: 1px solid #6D4100; -} - -a:hover tt { - background: #EEE; -} - - -@media screen and (max-width: 600px) { - - div.sphinxsidebar { - display: none; - } - - div.document { - width: 100%; - - } - - div.documentwrapper { - margin-left: 0; - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - } - - div.bodywrapper { - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - margin-left: 0; - } - - ul { - margin-left: 0; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .bodywrapper { - margin: 0; - } - - .footer { - width: auto; - } - - .github { - display: none; - } - -} - -/* misc. */ - -.revsys-inline { - display: none!important; -} diff --git a/docs/_themes/kr/static/small_flask.css b/docs/_themes/kr/static/small_flask.css deleted file mode 100644 index 8d55e95..0000000 --- a/docs/_themes/kr/static/small_flask.css +++ /dev/null @@ -1,90 +0,0 @@ -/* - * small_flask.css_t - * ~~~~~~~~~~~~~~~~~ - * - * :copyright: Copyright 2010 by Armin Ronacher. - * :license: Flask Design License, see LICENSE for details. - */ - -body { - margin: 0; - padding: 20px 30px; -} - -div.documentwrapper { - float: none; - background: white; -} - -div.sphinxsidebar { - display: block; - float: none; - width: 102.5%; - margin: 50px -30px -20px -30px; - padding: 10px 20px; - background: #333; - color: white; -} - -div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar a { - color: #aaa; -} - -div.sphinxsidebar p.logo { - display: none; -} - -div.document { - width: 100%; - margin: 0; -} - -div.related { - display: block; - margin: 0; - padding: 10px 0 20px 0; -} - -div.related ul, -div.related ul li { - margin: 0; - padding: 0; -} - -div.footer { - display: none; -} - -div.bodywrapper { - margin: 0; -} - -div.body { - min-height: 0; - padding: 0; -} - -.rtd_doc_footer { - display: none; -} - -.document { - width: auto; -} - -.footer { - width: auto; -} - -.footer { - width: auto; -} - -.github { - display: none; -}
\ No newline at end of file diff --git a/docs/_themes/kr/theme.conf b/docs/_themes/kr/theme.conf deleted file mode 100644 index 307a1f0..0000000 --- a/docs/_themes/kr/theme.conf +++ /dev/null @@ -1,7 +0,0 @@ -[theme] -inherit = basic -stylesheet = flasky.css -pygments_style = flask_theme_support.FlaskyStyle - -[options] -touch_icon = diff --git a/docs/advanced.rst b/docs/advanced.rst deleted file mode 100644 index 5f89515..0000000 --- a/docs/advanced.rst +++ /dev/null @@ -1,304 +0,0 @@ -Advanced Usage -============== - -This covers some advanced usage scenarios for raven Python. - -Alternative Installations -------------------------- - -If you want to use the latest git version you can get it from `the github -repository <https://github.com/getsentry/raven-python>`_:: - - git clone https://github.com/getsentry/raven-python - pip install raven-python - -Certain additional features can be installed by defining the feature when -``pip`` installing it. For instance to install all dependencies needed to -use the Flask integration, you can depend on ``raven[flask]``:: - - pip install raven[flask] - -For more information refer to the individual integration documentation. - -.. _python-client-config: - -Configuring the Client ----------------------- - -Settings are specified as part of the initialization of the client. The -client is a class that can be instantiated with a specific configuration -and all reporting can then happen from the instance of that object. -Typically an instance is created somewhere globally and then imported as -necessary. - -.. code-block:: python - - from raven import Client - - # Read configuration from the ``SENTRY_DSN`` environment variable - client = Client() - - # Manually specify a DSN - client = Client('___DSN___') - - -A reasonably configured client should generally include a few additional -settings: - -.. code-block:: python - - import os - import raven - - client = raven.Client( - dsn='___DSN___', - - # inform the client which parts of code are yours - # include_paths=['my.app'] - include_paths=[__name__.split('.', 1)[0]], - - # pass along the version of your application - # release='1.0.0' - # release=raven.fetch_package_version('my-app') - release=raven.fetch_git_sha(os.path.dirname(__file__)), - ) - -.. versionadded:: 5.2.0 - The *fetch_package_version* and *fetch_git_sha* helpers. - - -Client Arguments ----------------- - -The following are valid arguments which may be passed to the Raven client: - -.. describe:: dsn - - A Sentry compatible DSN as mentioned before:: - - dsn = '___DSN___' - -.. describe:: transport - - The HTTP transport class to use. By default this is an asynchronous worker - thread that runs in-process. - - For more information see :doc:`transports`. - -.. describe:: site - - An optional, arbitrary string to identify this client installation:: - - site = 'my site name' - -.. describe:: name - - This will override the ``server_name`` value for this installation. - Defaults to ``socket.gethostname()``:: - - name = 'sentry_rocks_' + socket.gethostname() - -.. describe:: release - - The version of your application. This will map up into a Release in - Sentry:: - - release = '1.0.3' - -.. describe:: environment - - The environment your application is running in:: - - environment = 'staging' - -.. describe:: tags - - Default tags to send with events:: - - tags = {'site': 'foo.com'} - -.. describe:: repos - - This describes local repositories that are reflected in your source code:: - - repos = { - 'raven': { - # the name of the repository as registered in Sentry - 'name': 'getsentry/raven-python', - # the prefix where the local source code is found in the repo - 'prefix': 'src', - } - } - - The repository key can either be a module name or the absolute path. When - a module name is given it will be automatically converted to its absolute path. - - For more information, see the :doc:`repos interface <../../../clientdev/interfaces/repos>` - docs. - -.. describe:: exclude_paths - - Extending this allow you to ignore module prefixes when we attempt to - discover which function an error comes from (typically a view):: - - exclude_paths = [ - 'django', - 'sentry', - 'raven', - 'lxml.objectify', - ] - -.. describe:: include_paths - - For example, in Django this defaults to your list of ``INSTALLED_APPS``, - and is used for drilling down where an exception is located:: - - include_paths = [ - 'django', - 'sentry', - 'raven', - 'lxml.objectify', - ] - -.. describe:: ignore_exceptions - - A list of exceptions to ignore:: - - ignore_exceptions = [ - 'Http404', - 'django.exceptions.http.Http404', - 'django.exceptions.*', - ValueError, - ] - - Each item can be either a string or a class. - String declaration is strict (ie. does not work for child exceptions) - whereas class declaration handle inheritance (ie. child exceptions are also ignored). - -.. describe:: sample_rate - - The sampling factor to apply to events. A value of 0.00 will deny sending - any events, and a value of 1.00 will send 100% of events. - - .. code-block:: python - - # send 50% of events - sample_rate = 0.5 - -.. describe:: list_max_length - - The maximum number of items a list-like container should store. - - If an iterable is longer than the specified length, the left-most - elements up to length will be kept. - - .. note:: This affects sets as well, which are unordered. - - :: - - list_max_length = 50 - -.. describe:: string_max_length - - The maximum characters of a string that should be stored. - - If a string is longer than the given length, it will be truncated down - to the specified size:: - - string_max_length = 200 - -.. describe:: auto_log_stacks - - Should Raven automatically log frame stacks (including locals) for all - calls as it would for exceptions:: - - auto_log_stacks = True - -.. describe:: processors - - A list of processors to apply to events before sending them to the - Sentry server. Useful for sending additional global state data or - sanitizing data that you want to keep off of the server:: - - processors = ( - 'raven.processors.SanitizePasswordsProcessor', - ) - -Sanitizing Data ---------------- - -Several processors are included with Raven to assist in data -sanitiziation. These are configured with the ``processors`` value. - -.. describe:: raven.processors.SanitizePasswordsProcessor - - Removes all keys which resemble ``password``, ``secret``, or - ``api_key`` within stacktrace contexts, HTTP bits (such as cookies, - POST data, the querystring, and environment), and extra data. - -.. describe:: raven.processors.RemoveStackLocalsProcessor - - Removes all stacktrace context variables. This will cripple the - functionality of Sentry, as you'll only get raw tracebacks, but it will - ensure no local scoped information is available to the server. - -.. describe:: raven.processors.RemovePostDataProcessor - - Removes the ``body`` of all HTTP data. - -Custom Grouping Behavior ------------------------- - -In some cases you may see issues where Sentry groups multiple events together -when they should be separate entities. In other cases, Sentry simply doesn't -group events together because they're so sporadic that they never look the same. - -Both of these problems can be addressed by specifying the ``fingerprint`` -attribute. - -For example, if you have HTTP 404 (page not found) errors, and you'd prefer they -deduplicate by taking into account the URL: - -.. code-block:: python - - client.captureException(fingerprint=['{{ default }}', 'http://my-url/']) - -.. sentry:edition:: hosted, on-premise - - For more information, see :ref:`custom-grouping`. - -Sampling Messages ------------------ - -There are two ways to sample messages: - -- Add sample_rate to the Client object - This sends a percentage of messages the reaching the Client to Sentry - -.. code-block:: python - - client = Client('___DSN___', sample_rate=0.5) # send 50% of events - -- Sample individual messages - -.. code-block:: python - - client = Client('___DSN___') # No sample_rate provided - - try: - 1 / 0 - except ZeroDivisionError: - client.captureException(sample_rate=0.5) # Send 50% of this event - -Alternatively, if you have SentryHandler configured in your logging stack, -you can send ``sample_rate`` in the ``extra`` kwarg in each log like this - -.. code-block:: python - - some_logger.warning('foo', extra={'sample_rate': 0.5}) # Send 50% of this event - -A Note on uWSGI ---------------- - -If you're using uWSGI you will need to add ``enable-threads`` to the -default invocation, or you will need to switch off of the threaded default -transport. diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 73b48b9..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,187 +0,0 @@ -API Reference -============= - -.. default-domain:: py - -This gives you an overview of the public API that raven-python exposes. - - -Client ------- - -.. py:class:: raven.Client(dsn=None, **kwargs) - - The client needs to be instanciated once and can then be used for - submitting events to the Sentry server. For information about the - configuration of that client and which parameters are accepted see - :ref:`python-client-config`. - - .. py:method:: capture(event_type, data=None, date=None, \ - time_spent=None, extra=None, stack=False, tags=None, **kwargs) - - This method is the low-level method for reporting events to - Sentry. It captures and processes an event and pipes it via the - configured transport to Sentry. - - Example:: - - capture('raven.events.Message', message='foo', data={ - 'request': { - 'url': '...', - 'data': {}, - 'query_string': '...', - 'method': 'POST', - }, - 'logger': 'logger.name', - }, extra={ - 'key': 'value', - }) - - :param event_type: the module path to the Event class. Builtins can - use shorthand class notation and exclude the - full module path. - :param data: the data base, useful for specifying structured data - interfaces. Any key which contains a '.' will be - assumed to be a data interface. - :param date: the datetime of this event. If not supplied the - current timestamp is used. - :param time_spent: a integer value representing the duration of the - event (in milliseconds) - :param extra: a dictionary of additional standard metadata. - :param stack: If set to `True` a stack frame is recorded together - with the event. - :param tags: dict of extra tags - :param sample_rate: a float in the range [0, 1] to sample this message. - This overrides the Client object's sample_rate - :param kwargs: extra keyword arguments are handled specific to the - reported event type. - :return: a tuple with a 32-length string identifying this event - - .. py:method:: captureMessage(message, **kwargs) - - This is a shorthand to reporting a message via :meth:`capture`. - It passes ``'raven.events.Message'`` as `event_type` and the - message along. All other keyword arguments are regularly - forwarded. - - Example:: - - client.captureMessage('This just happened!') - - .. py:method:: captureException(exc_info=None, **kwargs) - - This is a shorthand to reporting an exception via :meth:`capture`. - It passes ``'raven.events.Exception'`` as `event_type` and the - traceback along. All other keyword arguments are regularly - forwarded. - - If exc_info is not provided, or is set to True, then this method - will perform the ``exc_info = sys.exc_info()`` and the requisite - clean-up for you. - - Example:: - - try: - 1 / 0 - except Exception: - client.captureException() - - .. py:method:: captureBreadcrumb(message=None, timestamp=None, - level=None, category=None, data=None, - type=None, processor=None) - - Manually captures a breadcrumb in the internal buffer for the - current client's context. Instead of using this method you are - encouraged to instead use the :py:func:`raven.breadcrumbs.record` - function which records to the correct client automatically. - - .. py:method:: send(**data) - - Accepts all data parameters and serializes them, then sends then - onwards via the transport to Sentry. This can be used as to send - low-level protocol data to the server. - - .. py:attribute:: context - - Returns a reference to the thread local context object. See - :py:class:`raven.context.Context` for more information. - - .. py:method:: user_context(data) - - Updates the user context for future events. - - Equivalent to this:: - - client.context.merge({'user': data}) - - .. py:method:: http_context(data) - - Updates the HTTP context for future events. - - Equivalent to this:: - - client.context.merge({'request': data}) - - .. py:method:: extra_context(data) - - Update the extra context for future events. - - Equivalent to this:: - - client.context.merge({'extra': data}) - - .. py:method:: tags_context(data) - - Update the tags context for future events. - - Equivalent to this:: - - client.context.merge({'tags': data}) - -Context -------- - -.. py:class:: raven.context.Context() - - The context object works similar to a dictionary and is used to record - information that should be submitted with events automatically. It is - available through :py:attr:`raven.Client.context` and is thread local. - This means that you can modify this object over time to feed it with - more appropriate information. - - .. py:method:: activate() - - Binds the context to the current thread. This normally happens - automatically on first usage but if the context was deactivated - then this needs to be called again to bind it again. Only if a - context is bound to the thread breadcrumbs will be recorded. - - .. py:method:: deactivate() - - This deactivates the thread binding of the context. In particular - it means that breadcrumbs of the current thread are no longer - recorded to this context. - - .. py:method:: merge(data, activate=True) - - Performs a merge of the current data in the context and the new - data provided. This also automatically activates the context - by default. - - .. py:method:: clear(deactivate=None) - - Clears the context. It's important that you make sure to call - this when you reuse the thread for something else. For instance - for web frameworks it's generally a good idea to call this at the - end of the HTTP request. - - Otherwise you run at risk of seeing incorrect information after - the first use of the thread. - - Optionally `deactivate` parameter controls if the context should - automatically be deactivated. The default behavior is to - deactivate if the context was not created for the main thread. - - The context can also be used as a context manager. In that case - :py:meth:`activate` is called on enter and :py:meth:`deactivate` is - called on exit. diff --git a/docs/breadcrumbs.rst b/docs/breadcrumbs.rst deleted file mode 100644 index 642005d..0000000 --- a/docs/breadcrumbs.rst +++ /dev/null @@ -1,129 +0,0 @@ -Logging Breadcrumbs -=================== - -Newer Sentry versions support logging of breadcrumbs in addition of -errors. This means that whenever an error or other Sentry event is -submitted to the system, breadcrumbs that were logged before are sent -along to make it easier to reproduce what lead up to an error. - -In the default configuration the Python client instruments the logging -framework and a few popular libraries to emit crumbs. - -You can however also manually emit events if you want to do so. There are -a few ways this can be done. - -Breadcrumbs are enabled by default but starting with Raven 5.15 you can -disable them on a per-client basis by passing ``enable_breadcrumbs=False`` -to the client constructor. - -Enabling / Disabling Instrumentation ------------------------------------- - -When a sentry client is constructed then the raven library will by default -automatically instrument some popular libraries. There are a few ways -this can be controlled by passing parameters to the client constructor: - -``install_logging_hook``: - If this keyword argument is set to `False` the Python logging system - will not be instrumented. Note that this is a global instrumentation - so that if you are using multiple sentry clients at once you need to - disable this on all of them. - -``hook_libraries``: - This is a list of libraries that you want to hook. The default is to - hook all libraries that we have integrations for. If this is set to - an empty list then no libraries are hooked. - - The following libraries are supported currently: - - - ``'requests'``: hooks the Python requests library. - - ``'httplib'``: hooks the stdlib http library (also hooks urllib in - the process) - -Additionally framework integration will hook more things automatically. -For instance when you use Django, database queries will be recorded. - -Another option to control what happens is to register special handlers for -the logging system or to disable loggers entirely. For this you can use -the :py:func:`~raven.breadcrumbs.ignore_logger` and -:py:func:`~raven.breadcrumbs.register_special_log_handler` functions: - -.. py:function:: raven.breadcrumbs.ignore_logger(name_or_logger, allow_level=None) - - If called with the name of a logger, this will ignore all messages - that come from that logger. For instance if you have a very spammy - logger you can disable it this way. - -.. py:function:: raven.breadcrumbs.register_special_log_handler(name_or_logger, callback) - - Registers a callback for log handling. The callback is invoked - with given arguments: `logger`, `level`, `msg`, `args` and `kwargs` - which are the values passed to the logging system. If the callback - returns true value the default handling is disabled. Only one callback - can be registered per one logger name. Logger tree is not traversed - so calling this method with `spammy_module` argument will not silence - messages from `spammy_module.child`. - - Typically it makes sense to invoke - :py:func:`~raven.breadcrumbs.record` from it unless you want to silence - a message based on its attributes other than `level`. - -.. py:function:: raven.breadcrumbs.register_logging_handler(callback) - - This is similar to :py:func:`~raven.breadcrumbs.register_special_log_handler` - but it adds a global callback that is invoked for all log entries. - Otherwise it works the same but multiple handlers can be registered. - -Manually Emitting Breadcrumbs ------------------------------ - -If you want to manually record breadcrumbs the most convenient way to do -that is to use the :py:func:`~reaven.breadcrumbs.record` function -which will automatically record the crumbs with the clients that are -working with the current thread. This is more convenient than to call the -`captureBreadcrumb` method on the client itself as you need to hold a -reference to that. - -.. py:function:: raven.breadcrumbs.record(**options) - - This function accepts keyword arguments matching the attributes of a - breadcrumb. For more information see :doc:`/clientdev/interfaces/index`. - Additionally a `processor` callback can be passed which will be - invoked to process the data if the crumb was not rejected. - - The most important parameters: - - `message`: - the message that should be recorded. - `data`: - a data dictionary that should be recorded with the event. - `category`: - The category for this error. This can be a module name, or just a - string that clearly identifies the crumb (eg: `http`, `rpc`, etc.) - `type`: - can override the type if a special type should be sent to Sentry. - -Example: - -.. sourcecode:: python - - from raven import breadcrumbs - - breadcrumbs.record(message='This is an important message', - category='my_module', level='warning') - -Because crumbs go into a ring buffer, often it can be useful to defer -processing of expensive operations until the crumb is actually needed. -For this you can pass a processor which will be passed the data dict for -modifications: - -.. sourcecode:: python - - from raven.breadcrumbs import record - - def process_crumb(data): - data['data'] = compute_expensive_data() - - breadcrumbs.record(message='This is an important message', - category='my_module', level='warning', - processor=process_crumb) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 1f80ba4..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,231 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Sentry documentation build configuration file, created by -# sphinx-quickstart on Wed Oct 20 16:21:42 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import os -import sys -import datetime - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -#extensions = ['sphinxtogithub'] -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Raven' -copyright = u'%s, David Cramer' % datetime.datetime.today().year - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. - -version = __import__('pkg_resources').get_distribution('raven').version -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -intersphinx_mapping = { - 'http://docs.python.org/2.7': None, - 'django': ('http://docs.djangoproject.com/en/dev/', 'http://docs.djangoproject.com/en/dev/_objects/'), - 'https://raven.readthedocs.io/en/latest': None -} - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'kr' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = ['_themes'] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = "_static/logo.png" - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Ravendoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'Raven.tex', u'Raven Documentation', - u'David Cramer', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'raven', u'Raven Documentation', - [u'David Cramer'], 1) -] - -if os.environ.get('SENTRY_FEDERATED_DOCS') != '1': - sys.path.insert(0, os.path.abspath('_sentryext')) - import sentryext - sentryext.activate() diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index e08b112..0000000 --- a/docs/contributing.rst +++ /dev/null @@ -1,70 +0,0 @@ -Contributing -============ - -Want to contribute back to Sentry? This page describes the general development flow, -our philosophy, the test suite, and issue tracking. - -There are many ways to you can help, either by submitting bug reports, improving the -documentation, or submitting a patch. This document describes how to get the -test suite running for the Python SDK. - -Setting up an Environment -------------------------- - -There are several ways of setting up a development environment. If you want to ensure -your changes work across all environments and integrations that Raven supports, -the easiest way to run one or more jobs from test suite matrix is using a virtualenv -management and test command line tool called `Tox`_, - -It is also recommended to have the Python versions you are targeting installed on your -system. There are several tools that help you manage several Python installations, -like `Pyenv`_ or `Pythonz`_, but you can also install them manually by downloading them -from the Python.org website or installing them from repositories depending on your -operating system. - -Once you have the Python versions you are going to work with, you have to install `Tox`. -The easiest way of installing `Tox` is by running `pip install tox` into your -default Python installation. - -Running the tests ------------------ - -Running the tests is easy: just run `tox` from the command line and it will take care of -creating all the necessary virtualenvs and running all the environments defined in the `tox.ini` -file. - -During development you might want to run only a certain environment, which can be done by -passing the `-e ENV` to tox, for example: - -.. code-block:: bash - - $ tox -e py35-django19 - -which would run the Python3.5 environment and the Django integration tests with Django 1.9. -You can list all the defined environments with `tox --listenvs`, or fall into the Python debugger -on any raised exception by using `tox --pdb`. Please refer to the Tox Documentation for additional -information. - - -Contributing Back Code ----------------------- - -Ideally all patches should be sent as a pull request on GitHub, and include tests. -If you're fixing a bug or making a large change the patch **must** include test coverage. - -You can see a list of open pull requests (pending changes) by visiting our `Github Pull Request` page. -Every pull requests triggers a test build on our Travis CI where you can verify that -all tests pass. - -Notes ------ - -In order to use Pyenv with Tox, create a `.python-version` file similar to the -`.python-version-example` in the project root. - - -.. _Sentry: https://getsentry.com -.. _Github Pull Request: https://github.com/getsentry/raven-python/pulls -.. _Tox: https://tox.readthedocs.io -.. _Pythonz: https://github.com/saghul/pythonz -.. _Pyenv: https://github.com/pyenv/pyenv
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 6fe160e..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,132 +0,0 @@ -.. sentry:edition:: self - - Raven Python - ============ - -.. sentry:edition:: hosted, on-premise - - .. class:: platform-python - - Python - ====== - -For pairing Sentry up with Python you can use the Raven for Python -(raven-python) library. It is the official standalone Python client for -Sentry. It can be used with any modern Python interpreter be it CPython -2.x or 3.x, PyPy or Jython. It's an Open Source project and available -under a very liberal BSD license. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Configuring the Client ----------------------- - -Settings are specified as part of the initialization of the client. The -client is a class that can be instanciated with a specific configuration -and all reporting can then happen from the instance of that object. -Typically an instance is created somewhere globally and then imported as -necessary. For getting started all you need is your DSN: - -.. sourcecode:: python - - from raven import Client - client = Client('___DSN___') - -Capture an Error ----------------- - -The most basic use for raven is to record one specific error that occurs:: - - from raven import Client - - client = Client('___DSN___') - - try: - 1 / 0 - except ZeroDivisionError: - client.captureException() - -Adding Context --------------- - -Much of the usefulness of Sentry comes from additional context data with -the events. The Python client makes this very convenient by providing -methods to set thread local context data that is then submitted -automatically with all events. For instance you can use -:py:meth:`~raven.Client.user_context` to set the information about the -current user: - -.. sourcecode:: python - - def handle_request(request): - client.user_context({ - 'email': request.user.email - }) - -Deep Dive ---------- - -Raven Python is more than that however. To dive deeper into what it does, -how it works and how it integrates into other systems there is more to -discover: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - usage - advanced - breadcrumbs - integrations/index - transports - platform-support - api - -.. sentry:edition:: self - - For Developers - -------------- - - .. toctree:: - :maxdepth: 2 - :titlesonly: - - contributing - - Supported Platforms - ------------------- - - - Python 2.6 - - Python 2.7 - - Python 3.2 - - Python 3.3 - - Python 3.4 - - Python 3.5 - - PyPy - - Google App Engine - - Deprecation Notes - ----------------- - - Milestones releases are 1.3 or 1.4, and our deprecation policy is to a two - version step. For example, a feature will be deprecated in 1.3, and - completely removed in 1.4. - - Resources - --------- - -.. sentry:edition:: hosted, on-premise - - Resources: - -* `Documentation <https://docs.getsentry.com/hosted/clients/python/>`_ -* `Bug Tracker <http://github.com/getsentry/raven-python/issues>`_ -* `Code <http://github.com/getsentry/raven-python>`_ -* `Mailing List <https://groups.google.com/group/getsentry>`_ -* `IRC <irc://irc.freenode.net/sentry>`_ (irc.freenode.net, #sentry) diff --git a/docs/integrations/bottle.rst b/docs/integrations/bottle.rst deleted file mode 100644 index 4db312b..0000000 --- a/docs/integrations/bottle.rst +++ /dev/null @@ -1,54 +0,0 @@ -Bottle -====== - -`Bottle <http://bottlepy.org/>`_ is a microframework for Python. Raven -supports this framework through the WSGI integration. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ - -The first thing you'll need to do is to disable catchall in your Bottle app:: - - import bottle - - app = bottle.app() - app.catchall = False - -.. note:: Bottle will not propagate exceptions to the underlying WSGI - middleware by default. Setting catchall to False disables that. - -Sentry will then act as Middleware:: - - from raven import Client - from raven.contrib.bottle import Sentry - client = Client('___DSN___') - app = Sentry(app, client) - -Usage ------ - -Once you've configured the Sentry application you need only call run with it:: - - run(app=app) - -If you want to send additional events, a couple of shortcuts are provided -on the Bottle request app object. - -Capture an arbitrary exception by calling ``captureException``:: - - try: - 1 / 0 - except ZeroDivisionError: - request.app.sentry.captureException() - -Log a generic message with ``captureMessage``:: - - request.app.sentry.captureMessage('Hello, world!') diff --git a/docs/integrations/celery.rst b/docs/integrations/celery.rst deleted file mode 100644 index b242d88..0000000 --- a/docs/integrations/celery.rst +++ /dev/null @@ -1,62 +0,0 @@ -Celery -====== - -`Celery <http://www.celeryproject.org/>`_ is a distributed task queue -system for Python built on AMQP principles. For Celery built-in support -by Raven is provided but it requires some manual configuration. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ -To capture errors, you need to register a couple of signals to hijack -Celery error handling:: - - from raven import Client - from raven.contrib.celery import register_signal, register_logger_signal - - client = Client('___DSN___') - - # register a custom filter to filter out duplicate logs - register_logger_signal(client) - - # The register_logger_signal function can also take an optional argument - # `loglevel` which is the level used for the handler created. - # Defaults to `logging.ERROR` - register_logger_signal(client, loglevel=logging.INFO) - - # hook into the Celery error handler - register_signal(client) - - # The register_signal function can also take an optional argument - # `ignore_expected` which causes exception classes specified in Task.throws - # to be ignored - register_signal(client, ignore_expected=True) - -A more complex version to encapsulate behavior: - -.. code-block:: python - - import celery - import raven - from raven.contrib.celery import register_signal, register_logger_signal - - class Celery(celery.Celery): - - def on_configure(self): - client = raven.Client('___DSN___') - - # register a custom filter to filter out duplicate logs - register_logger_signal(client) - - # hook into the Celery error handler - register_signal(client) - - app = Celery(__name__) - app.config_from_object('django.conf:settings') diff --git a/docs/integrations/django.rst b/docs/integrations/django.rst deleted file mode 100644 index 0917c70..0000000 --- a/docs/integrations/django.rst +++ /dev/null @@ -1,398 +0,0 @@ -Django -====== - -.. default-domain:: py - -`Django <http://djangoproject.com/>`_ version 1.4 and newer are supported. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ - -Using the Django integration is as simple as adding -:mod:`raven.contrib.django.raven_compat` to your installed apps:: - - INSTALLED_APPS = ( - 'raven.contrib.django.raven_compat', - ) - -.. note:: This causes Raven to install a hook in Django that will - automatically report uncaught exceptions. - -Additional settings for the client are configured using the -``RAVEN_CONFIG`` dictionary:: - - import os - import raven - - RAVEN_CONFIG = { - 'dsn': '___DSN___', - # If you are using git, you can also automatically configure the - # release based on the git info. - 'release': raven.fetch_git_sha(os.path.abspath(os.pardir)), - } - -Once you've configured the client, you can test it using the standard Django -management interface:: - - python manage.py raven test - -You'll be referencing the client slightly differently in Django as well:: - - from raven.contrib.django.raven_compat.models import client - - client.captureException() - - -Using with Raven.js -------------------- - -A Django template tag is provided to render a proper public DSN inside -your templates, you must first load ``raven``: - -.. sourcecode:: django - - {% load raven %} - -Inside your template, you can now use: - -.. sourcecode:: html+django - - <script>Raven.config('{% sentry_public_dsn %}').install()</script> - -By default, the DSN is generated in a protocol relative fashion, e.g. -``//public@example.com/1``. If you need a specific protocol, you can -override: - -.. sourcecode:: html+django - - {% sentry_public_dsn 'https' %} - -.. sentry:edition:: hosted, on-premise - - See the :doc:`Raven.js documentation <../../../clients/javascript/index>` - for more information. - - -Integration with :mod:`logging` -------------------------------- - -To integrate with the standard library's :mod:`logging` module, and send all -ERROR and above messages to sentry, the following config can be used:: - - LOGGING = { - 'version': 1, - 'disable_existing_loggers': True, - 'root': { - 'level': 'WARNING', - 'handlers': ['sentry'], - }, - 'formatters': { - 'verbose': { - 'format': '%(levelname)s %(asctime)s %(module)s ' - '%(process)d %(thread)d %(message)s' - }, - }, - 'handlers': { - 'sentry': { - 'level': 'ERROR', # To capture more than ERROR, change to WARNING, INFO, etc. - 'class': 'raven.contrib.django.raven_compat.handlers.SentryHandler', - 'tags': {'custom-tag': 'x'}, - }, - 'console': { - 'level': 'DEBUG', - 'class': 'logging.StreamHandler', - 'formatter': 'verbose' - } - }, - 'loggers': { - 'django.db.backends': { - 'level': 'ERROR', - 'handlers': ['console'], - 'propagate': False, - }, - 'raven': { - 'level': 'DEBUG', - 'handlers': ['console'], - 'propagate': False, - }, - 'sentry.errors': { - 'level': 'DEBUG', - 'handlers': ['console'], - 'propagate': False, - }, - }, - } - -Usage -~~~~~ - -Logging usage works the same way as it does outside of Django, with the -addition of an optional ``request`` key in the extra data:: - - logger.error('There was some crazy error', exc_info=True, extra={ - # Optionally pass a request and we'll grab any information we can - 'request': request, - }) - - -404 Logging ------------ - -In certain conditions you may wish to log 404 events to the Sentry server. To -do this, you simply need to enable a Django middleware: - -.. sourcecode:: python - - # Use ``MIDDLEWARE_CLASSES`` prior to Django 1.10 - MIDDLEWARE = ( - 'raven.contrib.django.raven_compat.middleware.Sentry404CatchMiddleware', - ..., - ) + MIDDLEWARE - -It is recommended to put the middleware at the top, so that only 404s -that bubbled all the way up get logged. Certain middlewares (e.g. flatpages) -capture 404s and replace the response. - -It is also possible to configure this middleware to ignore 404s on particular -pages by defining the ``IGNORABLE_404_URLS`` setting as an iterable of regular -expression patterns. If any pattern produces a match against the full requested -URL (as defined by the regular expression's ``search`` method), then the 404 -will not be reported to Sentry. - -.. sourcecode:: python - - import re - - IGNORABLE_404_URLS = ( - re.compile('/foo'), - ) - -Message References ------------------- - -Sentry supports sending a message ID to your clients so that they can be -tracked easily by your development team. There are two ways to access this -information, the first is via the ``X-Sentry-ID`` HTTP response header. -Adding this is as simple as appending a middleware to your stack: - -.. sourcecode:: python - - # Use ``MIDDLEWARE_CLASSES`` prior to Django 1.10 - MIDDLEWARE = MIDDLEWARE + ( - # We recommend putting this as high in the chain as possible - 'raven.contrib.django.raven_compat.middleware.SentryResponseErrorIdMiddleware', - ..., - ) - -Another alternative method is rendering it within a template. By default, -Sentry will attach :attr:`request.sentry` when it catches a Django -exception. In our example, we will use this information to modify the -default :file:`500.html` which is rendered, and show the user a case -reference ID. The first step in doing this is creating a custom -:func:`handler500` in your :file:`urls.py` file: - -.. sourcecode:: python - - from django.conf.urls.defaults import * - - from django.views.defaults import page_not_found, server_error - from django.template.response import TemplateResponse - - def handler500(request): - """500 error handler which includes ``request`` in the context. - - Templates: `500.html` - Context: None - """ - - context = {'request': request} - template_name = '500.html' # You need to create a 500.html template. - return TemplateResponse(request, template_name, context, status=500) - -Once we've successfully added the :data:`request` context variable, adding the -Sentry reference ID to our :file:`500.html` is simple: - -.. sourcecode:: html+django - - <p>You've encountered an error, oh noes!</p> - {% if request.sentry.id %} - <p>If you need assistance, you may reference this error as - <strong>{{ request.sentry.id }}</strong>.</p> - {% endif %} - -WSGI Middleware ---------------- - -If you are using a WSGI interface to serve your app, you can also apply a -middleware which will ensure that you catch errors even at the fundamental -level of your Django application:: - - from raven.contrib.django.raven_compat.middleware.wsgi import Sentry - from django.core.wsgi import get_wsgi_application - - application = Sentry(get_wsgi_application()) - -.. _python-django-user-feedback: - -User Feedback -------------- - -To enable user feedback for crash reports, start with ensuring the ``request`` -value is available in your context processors: - -.. sourcecode:: python - - TEMPLATE_CONTEXT_PROCESSORS = ( - # ... - 'django.core.context_processors.request', - ) - -By default Django will render ``500.html``, so simply drop the following snippet -into your template: - -.. sourcecode:: html+django - - <!-- Sentry JS SDK 2.1.+ required --> - <script src="https://cdn.ravenjs.com/2.3.0/raven.min.js"></script> - - {% if request.sentry.id %} - <script> - Raven.showReportDialog({ - eventId: '{{ request.sentry.id }}', - - // use the public DSN (dont include your secret!) - dsn: '___PUBLIC_DSN___' - }); - </script> - {% endif %} - -That's it! - -For more details on this feature, see the :doc:`User Feedback guide <../../../learn/user-feedback>`. - -Additional Settings -------------------- - -.. describe:: SENTRY_CLIENT - - In some situations you may wish for a slightly different behavior to - how Sentry communicates with your server. For this, Raven allows you - to specify a custom client:: - - SENTRY_CLIENT = 'raven.contrib.django.raven_compat.DjangoClient' - -.. describe:: SENTRY_CELERY_LOGLEVEL - - If you are also using Celery, there is a handler being automatically - registered for you that captures the errors from workers. The default - logging level for that handler is ``logging.ERROR`` and can be - customized using this setting:: - - SENTRY_CELERY_LOGLEVEL = logging.INFO - - Alternatively you can use a similarly named key in ``RAVEN_CONFIG``:: - - RAVEN_CONFIG = { - 'CELERY_LOGLEVEL': logging.INFO - } - -.. describe:: SENTRY_CELERY_IGNORE_EXPECTED - - If you are also using Celery, then you can ignore expected exceptions by - setting this to ``True``. This will cause exception classes in - ``Task.throws`` to be ignored. - -Caveats -------- - -The following things you should keep in mind when using Raven with Django. - -Error Handling Middleware -~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you already have middleware in place that handles :func:`process_exception` -you will need to take extra care when using Sentry. - -For example, the following middleware would suppress Sentry logging due to it -returning a response: - -.. sourcecode:: python - - class MyMiddleware(object): - def process_exception(self, request, exception): - return HttpResponse('foo') - -To work around this, you can either disable your error handling middleware, or -add something like the following: - -.. sourcecode:: python - - from django.core.signals import got_request_exception - - class MyMiddleware(object): - def process_exception(self, request, exception): - # Make sure the exception signal is fired for Sentry - got_request_exception.send(sender=self, request=request) - return HttpResponse('foo') - -Note that this technique may break unit tests using the Django test client -(:class:`django.test.client.Client`) if a view under test generates a -:exc:`Http404 <django.http.Http404>` or :exc:`PermissionDenied` exception, -because the exceptions won't be translated into the expected 404 or 403 -response codes. - -Or, alternatively, you can just enable Sentry responses: - -.. sourcecode:: python - - from raven.contrib.django.raven_compat.models import sentry_exception_handler - - class MyMiddleware(object): - def process_exception(self, request, exception): - # Make sure the exception signal is fired for Sentry - sentry_exception_handler(request=request) - return HttpResponse('foo') - -Circus -~~~~~~ - -If you are running Django with `circus <http://circus.rtfd.org/>`_ and -`chaussette <https://chaussette.readthedocs.io/>`_ you will also need -to add a hook to circus to activate Raven: - -.. sourcecode:: python - - from django.conf import settings - from django.core.management import call_command - - def run_raven(*args, **kwargs): - """Set up raven for django by running a django command. - It is necessary because chaussette doesn't run a django command. - """ - if not settings.configured: - settings.configure() - - call_command('validate') - return True - -And in your circus configuration: - -.. sourcecode:: ini - - [socket:dwebapp] - host = 127.0.0.1 - port = 8080 - - [watcher:dwebworker] - cmd = chaussette --fd $(circus.sockets.dwebapp) dproject.wsgi.application - use_sockets = True - numprocesses = 2 - hooks.after_start = dproject.hooks.run_raven diff --git a/docs/integrations/flask.rst b/docs/integrations/flask.rst deleted file mode 100644 index ad3403c..0000000 --- a/docs/integrations/flask.rst +++ /dev/null @@ -1,228 +0,0 @@ -Flask -===== - -Installation ------------- - -If you haven't already, install raven with its explicit Flask dependencies:: - - pip install raven[flask] - -Setup ------ - -The first thing you'll need to do is to initialize Raven under your application:: - - from raven.contrib.flask import Sentry - sentry = Sentry(app, dsn='___DSN___') - -If you don't specify the ``dsn`` value, we will attempt to read it from -your environment under the ``SENTRY_DSN`` key. - -Extended Setup --------------- - -You can optionally configure logging too: - -.. sourcecode:: python - - import logging - from raven.contrib.flask import Sentry - sentry = Sentry(app, logging=True, level=logging.ERROR, \ - logging_exclusions=("logger1", "logger2", ...)) - -Building applications on the fly? You can use Raven's ``init_app`` hook: - -.. sourcecode:: python - - sentry = Sentry(dsn='http://public_key:secret_key@example.com/1') - - def create_app(): - app = Flask(__name__) - sentry.init_app(app) - return app - -You can pass parameters in the ``init_app`` hook: - -.. sourcecode:: python - - sentry = Sentry() - - def create_app(): - app = Flask(__name__) - sentry.init_app(app, dsn='___DSN___', logging=True, - level=logging.ERROR, - logging_exclusions=("logger1", "logger2", ...)) - return app - -Settings --------- - -Additional settings for the client can be configured using -``SENTRY_CONFIG`` in your application's configuration: - -.. sourcecode:: python - - class MyConfig(object): - SENTRY_CONFIG = { - 'dsn': '___DSN___', - 'include_paths': ['myproject'], - 'release': raven.fetch_git_sha(os.path.dirname(__file__)), - } - -If `Flask-Login <https://pypi.python.org/pypi/Flask-Login/>`_ is used by -your application (including `Flask-Security -<https://pypi.python.org/pypi/Flask-Security/>`_), user information will -be captured when an exception or message is captured. By default, only -the ``id`` (current_user.get_id()), ``is_authenticated``, and -``is_anonymous`` is captured for the user. If you would like additional -attributes on the ``current_user`` to be captured, you can configure them -using ``SENTRY_USER_ATTRS``: - -.. sourcecode:: python - - class MyConfig(object): - SENTRY_USER_ATTRS = ['username', 'first_name', 'last_name', 'email'] - -``email`` will be captured as ``sentry.interfaces.User.email``, and any -additional attributes will be available under -``sentry.interfaces.User.data`` - -You can specify the types of exceptions that should not be reported by -Sentry client in your application by setting the ``ignore_exceptions`` -configuration value: - -.. sourcecode:: python - - class MyExceptionType(Exception): - def __init__(self, message): - super(MyExceptionType, self).__init__(message) - - app = Flask(__name__) - app.config['SENTRY_CONFIG'] = { - 'ignore_exceptions': [MyExceptionType], - } - -Usage ------ - -Once you've configured the Sentry application it will automatically -capture uncaught exceptions within Flask. If you want to send additional -events, a couple of shortcuts are provided on the Sentry Flask middleware -object. - -Capture an arbitrary exception by calling ``captureException``: - -.. sourcecode:: python - - try: - 1 / 0 - except ZeroDivisionError: - sentry.captureException() - -Log a generic message with ``captureMessage``: - -.. sourcecode:: python - - sentry.captureMessage('hello, world!') - -Getting The Last Event ID -------------------------- - -If possible, the last Sentry event ID is stored in the request context -``g.sentry_event_id`` variable. This allow to present the user an error -ID if have done a custom error 500 page. - -.. sourcecode:: html+jinja - - <h2>Error 500</h2> - {% if g.sentry_event_id %} - <p>The error identifier is {{ g.sentry_event_id }}</p> - {% endif %} - -.. _python-flask-user-feedback: - -User Feedback -------------- - -To enable user feedback for crash reports just make sure you have a custom -`500` error handler and render out a HTML snippet for bringing up the -crash dialog: - -.. sourcecode:: python - - from flask import Flask, g, render_template - from raven.contrib.flask import Sentry - - app = Flask(__name__) - sentry = Sentry(app, dsn='___DSN___') - - @app.errorhandler(500) - def internal_server_error(error): - return render_template('500.html', - event_id=g.sentry_event_id, - public_dsn=sentry.client.get_public_dsn('https') - ) - -And in the error template (``500.html``) you can then do this: - -.. sourcecode:: html+jinja - - <!-- Sentry JS SDK 2.1.+ required --> - <script src="https://cdn.ravenjs.com/2.3.0/raven.min.js"></script> - - {% if event_id %} - <script> - Raven.showReportDialog({ - eventId: '{{ event_id }}', - dsn: '{{ public_dsn }}' - }); - </script> - {% endif %} - -That's it! - -For more details on this feature, see the :doc:`User Feedback guide -<../../../learn/user-feedback>`. - -Dealing With Proxies --------------------- - -When your Flask application is behind a proxy such as nginx, Sentry will -use the remote address from the proxy, rather than from the actual -requesting computer. By using ``ProxyFix`` from `werkzeug.contrib.fixers -<http://werkzeug.pocoo.org/docs/0.10/contrib/fixers/#werkzeug.contrib.fixers.ProxyFix>`_ -the Flask ``.wsgi_app`` can be modified to send the actual ``REMOTE_ADDR`` -along to Sentry. :: - - from werkzeug.contrib.fixers import ProxyFix - app.wsgi_app = ProxyFix(app.wsgi_app) - -This may also require `changes -<http://flask.pocoo.org/docs/0.10/deploying/wsgi-standalone/#proxy-setups>`_ -to the proxy configuration to pass the right headers if it isn't doing so -already. - - -Signals -------- - -Raven uses `blinker <https://github.com/jek/blinker>`_ to emit a signal -(called ``logging_configured``) after logging has been configured for the -client. You may `bind to that signal <https://pythonhosted.org/blinker/#subscribing-to-signals>`_ -in your application to do any additional configuration to the logging -handler ``SentryHandler``. - -.. sourcecode:: python - - from raven.contrib.flask import Sentry, logging_configured - from flask import Flask, g, render_template - from raven.contrib.flask import Sentry - - app = Flask(__name__) - sentry = Sentry(app, dsn='___DSN___', logging=True) - - @logging_configured.connect - def internal_server_error(sender, sentry_handler=None, **kwargs): - # configure sentry_handler here - sentry_handler.addFilter(some_filter) diff --git a/docs/integrations/index.rst b/docs/integrations/index.rst deleted file mode 100644 index 460681e..0000000 --- a/docs/integrations/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -Integrations -============ - -The Raven Python module also comes with integration for some commonly used -libraries to automatically capture errors from common environments. This -means that once you have such an integration configured you typically do -not need to report errors manually. - -Some integrations allow specifying these in a standard configuration, -otherwise they are generally passed upon instantiation of the Sentry -client. - -.. toctree:: - :maxdepth: 1 - - bottle - celery - django - flask - lambda - logbook - logging - pylons - pyramid - rq - tornado - wsgi - zconfig - zerorpc - zope diff --git a/docs/integrations/lambda.rst b/docs/integrations/lambda.rst deleted file mode 100644 index 07ac0db..0000000 --- a/docs/integrations/lambda.rst +++ /dev/null @@ -1,54 +0,0 @@ -Amazon Web Services Lambda -========================== - -.. default-domain:: py - - - -Installation ------------- - -To use `Sentry`_ with `AWS Lambda`_, you have to install `raven` as an external -dependency. This involves creating a `Deployment package`_ and uploading it -to AWS. - -To install raven into your current project directory: - -.. code-block:: console - - pip install raven -t /path/to/project-dir - -Setup ------ - -Create a `LambdaClient` instance and wrap your lambda handler with -the `capture_exeptions` decorator: - - -.. sourcecode:: python - - from raven.contrib.awslambda import LambdaClient - - - client = LambdaClient() - - @client.capture_exceptions - def handler(event, context): - ... - raise Exception('I will be sent to sentry!') - - -By default this will report unhandled exceptions and errors to Sentry. - -Additional settings for the client are configured using environment variables or -subclassing `LambdaClient`. - - -The integration was inspired by `raven python lambda`_, another implementation that -also integrates with Serverless Framework and has SQS transport support. - - -.. _Sentry: https://getsentry.com/ -.. _AWS Lambda: https://aws.amazon.com/lambda -.. _Deployment package: https://docs.aws.amazon.com/lambda/latest/dg/lambda-python-how-to-create-deployment-package.html -.. _raven python lambda: https://github.com/Netflix-Skunkworks/raven-python-lambda diff --git a/docs/integrations/logbook.rst b/docs/integrations/logbook.rst deleted file mode 100644 index 8a2811e..0000000 --- a/docs/integrations/logbook.rst +++ /dev/null @@ -1,38 +0,0 @@ -Logbook -======= - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ -Raven provides a `logbook <http://logbook.pocoo.org>`_ handler which will pipe -messages to Sentry. - -First you'll need to configure a handler:: - - from raven.handlers.logbook import SentryHandler - - # Manually specify a client - client = Client(...) - handler = SentryHandler(client) - -You can also automatically configure the default client with a DSN:: - - # Configure the default client - handler = SentryHandler('___DSN___') - -Finally, bind your handler to your context:: - - from raven.handlers.logbook import SentryHandler - - client = Client(...) - sentry_handler = SentryHandler(client) - with sentry_handler.applicationbound(): - # everything logged here will go to sentry. - ... diff --git a/docs/integrations/logging.rst b/docs/integrations/logging.rst deleted file mode 100644 index 106a17b..0000000 --- a/docs/integrations/logging.rst +++ /dev/null @@ -1,165 +0,0 @@ -Logging -======= - -.. default-domain:: py - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ -Sentry supports the ability to directly tie into the :mod:`logging` -module. To use it simply add :class:`SentryHandler` to your logger. - -First you'll need to configure a handler:: - - from raven.handlers.logging import SentryHandler - - # Manually specify a client - client = Client(...) - handler = SentryHandler(client) - -You can also automatically configure the default client with a DSN:: - - # Configure the default client - handler = SentryHandler('___DSN___') - -You may want to specify the logging level at this point so you don't send INFO or DEBUG messages to Sentry:: - - handler.setLevel(logging.ERROR) - -Finally, call the :func:`setup_logging` helper function:: - - from raven.conf import setup_logging - - setup_logging(handler) - -Another option is to use :mod:`logging.config.dictConfig`:: - - LOGGING = { - 'version': 1, - 'disable_existing_loggers': True, - - 'formatters': { - 'console': { - 'format': '[%(asctime)s][%(levelname)s] %(name)s ' - '%(filename)s:%(funcName)s:%(lineno)d | %(message)s', - 'datefmt': '%H:%M:%S', - }, - }, - - 'handlers': { - 'console': { - 'level': 'DEBUG', - 'class': 'logging.StreamHandler', - 'formatter': 'console' - }, - 'sentry': { - 'level': 'ERROR', - 'class': 'raven.handlers.logging.SentryHandler', - 'dsn': '___DSN___', - }, - }, - - 'loggers': { - '': { - 'handlers': ['console', 'sentry'], - 'level': 'DEBUG', - 'propagate': False, - }, - 'your_app': { - 'level': 'DEBUG', - 'propagate': True, - }, - } - } - -Usage -~~~~~ - -A recommended pattern in logging is to simply reference the modules name for -each logger, so for example, you might at the top of your module define the -following:: - - import logging - logger = logging.getLogger(__name__) - -You can also use the ``exc_info`` and ``extra={'stack': True}`` arguments on -your ``log`` methods. This will store the appropriate information and allow -Sentry to render it based on that information:: - - # If you're actually catching an exception, use `exc_info=True` - logger.error('There was an error, with a stacktrace!', exc_info=True) - - # If you don't have an exception, but still want to capture a - # stacktrace, use the `stack` arg - logger.error('There was an error, with a stacktrace!', extra={ - 'stack': True, - }) - -.. note:: Depending on the version of Python you're using, ``extra`` might - not be an acceptable keyword argument for a logger's ``.exception()`` - method (``.debug()``, ``.info()``, ``.warning()``, ``.error()`` and - ``.critical()`` should work fine regardless of Python version). This - should be fixed as of Python 2.7.4 and 3.2. Official issue here: - http://bugs.python.org/issue15541. - -While we don't recommend this, you can also enable implicit stack -capturing for all messages:: - - client = Client(..., auto_log_stacks=True) - handler = SentryHandler(client) - - logger.error('There was an error, with a stacktrace!') - -Passing tags and user context is also available through extra:: - - logger.error('There was an error, with user context and tags'), extra={ - 'user': {'email': 'test@test.com'}, - 'tags': {'database': '1.0'}, - }) - -You may also pass additional information to be stored as meta information with -the event. As long as the key name is not reserved and not private (_foo) it -will be displayed on the Sentry dashboard. To do this, pass it as ``data`` -within your ``extra`` clause:: - - logger.error('There was some crazy error', exc_info=True, extra={ - # Optionally you can pass additional arguments to specify request info - 'culprit': 'my.view.name', - 'fingerprint': [...], - - 'data': { - # You may specify any values here and Sentry will log and output them - 'username': request.user.username, - } - }) - -.. note:: The ``url`` and ``view`` keys are used internally by Sentry - within the extra data. - -.. note:: Any key (in ``data``) prefixed with ``_`` will not automatically - output on the Sentry details view. - -Sentry will intelligently group messages if you use proper string -formatting. For example, the following messages would be seen as the same -message within Sentry:: - - logger.error('There was some %s error', 'crazy') - logger.error('There was some %s error', 'fun') - logger.error('There was some %s error', 1) - -Exclusions -~~~~~~~~~~ - -You can also configure some logging exclusions during setup. These loggers -will not propagate their logs to the Sentry handler:: - - from raven.conf import setup_logging - - setup_logging(handler, exclude=("logger1", "logger2", ...)) diff --git a/docs/integrations/pylons.rst b/docs/integrations/pylons.rst deleted file mode 100644 index 53347b7..0000000 --- a/docs/integrations/pylons.rst +++ /dev/null @@ -1,77 +0,0 @@ -Pylons -====== - -Pylons is a framework for Python. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -WSGI Middleware ---------------- - -A Pylons-specific middleware exists to enable easy configuration from settings: - -:: - - from raven.contrib.pylons import Sentry - - application = Sentry(application, config) - -Configuration is handled via the sentry namespace: - -.. code-block:: ini - - [sentry] - dsn=___DSN___ - include_paths=my.package,my.other.package, - exclude_paths=my.package.crud - - -Logger setup ------------- - -Add the following lines to your project's `.ini` file to setup `SentryHandler`: - -.. code-block:: ini - - [loggers] - keys = root, sentry - - [handlers] - keys = console, sentry - - [formatters] - keys = generic - - [logger_root] - level = INFO - handlers = console, sentry - - [logger_sentry] - level = WARN - handlers = console - qualname = sentry.errors - propagate = 0 - - [handler_console] - class = StreamHandler - args = (sys.stderr,) - level = NOTSET - formatter = generic - - [handler_sentry] - class = raven.handlers.logging.SentryHandler - args = ('SENTRY_DSN',) - level = NOTSET - formatter = generic - - [formatter_generic] - format = %(asctime)s,%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s - datefmt = %H:%M:%S - -.. note:: You may want to setup other loggers as well. diff --git a/docs/integrations/pyramid.rst b/docs/integrations/pyramid.rst deleted file mode 100644 index 41d247e..0000000 --- a/docs/integrations/pyramid.rst +++ /dev/null @@ -1,79 +0,0 @@ -Pyramid -======= - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -PasteDeploy Filter ------------------- - -A filter factory for `PasteDeploy <https://pastedeploy.readthedocs.io/en/latest/>`_ exists to allow easily inserting Raven into a WSGI pipeline: - -.. code-block:: ini - - [pipeline:main] - pipeline = - raven - tm - MyApp - - [filter:raven] - use = egg:raven#raven - dsn = ___DSN___ - include_paths = my.package, my.other.package - exclude_paths = my.package.crud - -In the ``[filter:raven]`` section, you must specify the entry-point for raven with the ``use =`` key. All other raven client parameters can be included in this section as well. - -See the `Pyramid PasteDeploy Configuration Documentation <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/paste.html>`_ for more information. - -Logger setup ------------- - -Add the following lines to your project's `.ini` file to setup `SentryHandler`: - -.. code-block:: ini - - [loggers] - keys = root, sentry - - [handlers] - keys = console, sentry - - [formatters] - keys = generic - - [logger_root] - level = INFO - handlers = console, sentry - - [logger_sentry] - level = WARN - handlers = console - qualname = sentry.errors - propagate = 0 - - [handler_console] - class = StreamHandler - args = (sys.stderr,) - level = NOTSET - formatter = generic - - [handler_sentry] - class = raven.handlers.logging.SentryHandler - args = ('___DSN___',) - level = WARNING - formatter = generic - - [formatter_generic] - format = %(asctime)s,%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s - datefmt = %H:%M:%S - -.. note:: You may want to setup other loggers as well. See the `Pyramid Logging Documentation <http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html>`_ for more information. - -Instead of defining the DSN in the `.ini` file you can also use the environment variable ``SENTRY_DSN`` which overwrites the setting in this file. Because of a syntax check you cannot remove the ``args`` setting completely, as workaround you can define an empty list of arguments ``args = ()``. diff --git a/docs/integrations/rq.rst b/docs/integrations/rq.rst deleted file mode 100644 index 5adba36..0000000 --- a/docs/integrations/rq.rst +++ /dev/null @@ -1,30 +0,0 @@ -RQ -== - -Starting with RQ version 0.3.1, support for Sentry has been built in. - -Usage ------ - -RQ natively supports binding with Sentry by passing your ``SENTRY_DSN`` through ``rqworker``:: - - $ rqworker --sentry-dsn="___DSN___" - - -Extended Setup --------------- - -If you want to pass additional information, such as ``release``, you'll need to bind your -own instance of the Sentry ``Client``: - -.. code-block:: python - - from raven import Client - from raven.transport.http import HTTPTransport - from rq.contrib.sentry import register_sentry - - client = Client('___DSN___', transport=HTTPTransport) - register_sentry(client, worker) - -Please see ``rq``'s documentation for more information: -http://python-rq.org/patterns/sentry/ diff --git a/docs/integrations/tornado.rst b/docs/integrations/tornado.rst deleted file mode 100644 index 96ee43e..0000000 --- a/docs/integrations/tornado.rst +++ /dev/null @@ -1,114 +0,0 @@ -Tornado -======= - -Tornado is an async web framework for Python. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ - -The first thing you'll need to do is to initialize sentry client under -your application - -.. code-block:: python - - import tornado.web - from raven.contrib.tornado import AsyncSentryClient - - class MainHandler(tornado.web.RequestHandler): - def get(self): - self.write("Hello, world") - - application = tornado.web.Application([ - (r"/", MainHandler), - ]) - application.sentry_client = AsyncSentryClient( - '___DSN___' - ) - - -Usage ------ - -Once the sentry client is attached to the application, request handlers -can automatically capture uncaught exceptions by inheriting the `SentryMixin` class. - -.. code-block:: python - - import tornado.web - from raven.contrib.tornado import SentryMixin - - class UncaughtExceptionExampleHandler( - SentryMixin, tornado.web.RequestHandler): - def get(self): - 1/0 - - -You can also send events manually using the shortcuts defined in `SentryMixin`. -The shortcuts can be used for both asynchronous and synchronous usage. - - -Asynchronous -~~~~~~~~~~~~ - -.. code-block:: python - - import tornado.web - import tornado.gen - from raven.contrib.tornado import SentryMixin - - class AsyncMessageHandler(SentryMixin, tornado.web.RequestHandler): - @tornado.web.asynchronous - @tornado.gen.engine - def get(self): - self.write("You requested the main page") - yield tornado.gen.Task( - self.captureMessage, "Request for main page served" - ) - self.finish() - - class AsyncExceptionHandler(SentryMixin, tornado.web.RequestHandler): - @tornado.web.asynchronous - @tornado.gen.engine - def get(self): - try: - raise ValueError() - except Exception as e: - response = yield tornado.gen.Task( - self.captureException, exc_info=True - ) - self.finish() - - -.. tip:: - - The value returned by the yield is a ``HTTPResponse`` object. - - To dynamically use Python if configuration DSN available, change your base handler on fly and make sure all concrete handlers are imported after this. - - .. code-block:: python - - from raven.contrib.tornado import SentryMixin - app.sentry_client = AsyncSentryClient(dsn) - BaseHandler.__bases__ = (SentryMixin, ) + BaseHandler.__bases__ - - -Synchronous -~~~~~~~~~~~ - -.. code-block:: python - - import tornado.web - from raven.contrib.tornado import SentryMixin - - class AsyncExampleHandler(SentryMixin, tornado.web.RequestHandler): - def get(self): - self.write("You requested the main page") - self.captureMessage("Request for main page served") diff --git a/docs/integrations/wsgi.rst b/docs/integrations/wsgi.rst deleted file mode 100644 index c72c293..0000000 --- a/docs/integrations/wsgi.rst +++ /dev/null @@ -1,16 +0,0 @@ -WSGI Middleware -=============== - -Raven includes a simple to use WSGI middleware. - -:: - - from raven import Client - from raven.middleware import Sentry - - application = Sentry( - application, - Client('___DSN___') - ) - -.. note:: Many frameworks will not propagate exceptions to the underlying WSGI middleware by default. diff --git a/docs/integrations/zconfig.rst b/docs/integrations/zconfig.rst deleted file mode 100644 index 79d087a..0000000 --- a/docs/integrations/zconfig.rst +++ /dev/null @@ -1,33 +0,0 @@ -ZConfig logging configuration -============================= - -`ZConfig -<http://zconfig.readthedocs.io/en/latest/using-logging.html>`_ -provides a configuration mechanism for the Python logging module. - -To learn more, see: - - http://zconfig.readthedocs.io/en/latest/using-logging.html - -To use with sentry, use the sentry handler tag: - -.. code-block:: xml - - <logger> - level INFO - <logfile> - path ${buildout:directory}/var/{:_buildout_section_name_}.log - level INFO - </logfile> - - %import raven.contrib.zconfig - <sentry> - dsn ___DSN___ - level ERROR - </sentry> - </logger> - -This configuration retains normal logging to a logfile, but adds -Sentry logging for ERRORs. - -All options of :py:class:`raven.base.Client` are supported. diff --git a/docs/integrations/zerorpc.rst b/docs/integrations/zerorpc.rst deleted file mode 100644 index c60833b..0000000 --- a/docs/integrations/zerorpc.rst +++ /dev/null @@ -1,39 +0,0 @@ -ZeroRPC -======= - -ZeroRPC is a light-weight, reliable and language-agnostic library for -distributed communication between server-side processes. - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -Setup ------ - -The ZeroRPC integration comes as middleware for ZeroRPC. The middleware can be -configured like the original Raven client (using keyword arguments) and -registered into ZeroRPC's context manager:: - - import zerorpc - - from raven.contrib.zerorpc import SentryMiddleware - - sentry = SentryMiddleware(dsn='___DSN___') - zerorpc.Context.get_instance().register_middleware(sentry) - -By default, the middleware will hide internal frames from ZeroRPC when it -submits exceptions to Sentry. This behavior can be disabled by passing the -``hide_zerorpc_frames`` parameter to the middleware:: - - sentry = SentryMiddleware(hide_zerorpc_frames=False, dsn='___DSN___') - -Compatibility -------------- - -- ZeroRPC-Python < 0.4.0 is compatible with Raven <= 3.1.0; -- ZeroRPC-Python >= 0.4.0 requires Raven > 3.1.0. diff --git a/docs/integrations/zope.rst b/docs/integrations/zope.rst deleted file mode 100644 index e77a2d6..0000000 --- a/docs/integrations/zope.rst +++ /dev/null @@ -1,74 +0,0 @@ -Zope/Plone -========== - -Installation ------------- - -If you haven't already, start by downloading Raven. The easiest way is -with *pip*:: - - pip install raven --upgrade - -zope.conf ---------- - -Zope has extensible logging configuration options. -A basic instance (not ZEO client) setup for logging looks like this: - -.. code-block:: xml - - <eventlog> - level INFO - <logfile> - path ${buildout:directory}/var/{:_buildout_section_name_}.log - level INFO - </logfile> - - %import raven.contrib.zope - <sentry> - dsn ___DSN___ - level ERROR - </sentry> - </eventlog> - -This configuration retains normal logging to a logfile, but adds -Sentry logging for ERRORs. - -All options of :py:class:`raven.base.Client` are supported. - -Use a buildout recipe instead of editing zope.conf directly. -To add the equivalent instance configuration, you would do this: - -.. code-block:: ini - - [instance] - recipe = plone.recipe.zope2instance - ... - event-log-custom = - %import raven.contrib.zope - <logfile> - path ${buildout:directory}/var/instance.log - level INFO - </logfile> - <sentry> - dsn ___DSN___ - level ERROR - </sentry> - -To add the equivalent ZEO client configuration, you would do this: - -.. code-block:: ini - - [instance] - recipe = plone.recipe.zope2instance - ... - event-log-custom = - %import raven.contrib.zope - <logfile> - path ${buildout:var-dir}/${:_buildout_section_name_}/event.log - level INFO - </logfile> - <sentry> - dsn ___DSN___ - level ERROR - </sentry> diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 5c12e4a..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,155 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^<target^>` where ^<target^> is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Sentry.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Sentry.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/docs/platform-support.rst b/docs/platform-support.rst deleted file mode 100644 index dd0fa96..0000000 --- a/docs/platform-support.rst +++ /dev/null @@ -1,11 +0,0 @@ -Supported Platforms -=================== - -- Python 2.6 -- Python 2.7 -- Python 3.2 -- Python 3.3 -- Python 3.5 -- Python 3.6 -- PyPy -- Google App Engine diff --git a/docs/sentry-doc-config.json b/docs/sentry-doc-config.json deleted file mode 100644 index 11525fd..0000000 --- a/docs/sentry-doc-config.json +++ /dev/null @@ -1,93 +0,0 @@ -{ - "support_level": "production", - "platforms": { - "python": { - "name": "Python", - "type": "language", - "doc_link": "", - "wizard": [ - "index#installation", - "usage#capture-an-error", - "usage#reporting-an-event" - ] - }, - "python.flask": { - "name": "Flask", - "type": "framework", - "doc_link": "integrations/flask/", - "wizard": [ - "index#installation", - "integrations/flask#installation", - "integrations/flask#setup" - ] - }, - "python.bottle": { - "name": "Bottle", - "type": "framework", - "doc_link": "integrations/bottle/", - "wizard": [ - "index#installation", - "integrations/bottle#setup", - "integrations/bottle#usage" - ] - }, - "python.celery": { - "name": "Celery", - "type": "library", - "doc_link": "integrations/celery/", - "wizard": [ - "index#installation", - "integrations/celery" - ] - }, - "python.django": { - "name": "Django", - "type": "framework", - "doc_link": "integrations/django/", - "wizard": [ - "index#installation", - "integrations/django#setup" - ] - }, - "python.pylons": { - "name": "Pylons", - "type": "framework", - "doc_link": "integrations/pylons/", - "wizard": [ - "index#installation", - "integrations/pylons#wsgi-middleware", - "integrations/pylons#logger-setup" - ] - }, - "python.pyramid": { - "name": "Pyramid", - "type": "framework", - "doc_link": "integrations/pyramid/", - "wizard": [ - "index#installation", - "integrations/pyramid#pastedeploy-filter", - "integrations/pyramid#logger-setup" - ] - }, - "python.rq": { - "name": "RQ", - "type": "framework", - "doc_link": "integrations/rq/", - "wizard": [ - "index#installation", - "integrations/rq#usage", - "integrations/rq#extended-setup" - ] - }, - "python.tornado": { - "name": "Tornado", - "type": "framework", - "doc_link": "integrations/tornado/", - "wizard": [ - "index#installation", - "integrations/tornado#setup", - "integrations/tornado#usage" - ] - } - } -} diff --git a/docs/transports.rst b/docs/transports.rst deleted file mode 100644 index 19cb12d..0000000 --- a/docs/transports.rst +++ /dev/null @@ -1,124 +0,0 @@ -Transports -========== - -A transport is the mechanism in which Raven sends the HTTP request to the -Sentry server. By default, Raven uses a threaded asynchronous transport, -but you can easily adjust this by passing your own transport class. - - -The transport class is passed via the ``transport`` parameter on ``Client``: - -.. code-block:: python - - from raven import Client - - Client('...', transport=TransportClass) - -Options are passed to transports via the querystring. - -All transports should support at least the following options: - -``timeout = 1`` - The time to wait for a response from the server, in seconds. - -``verify_ssl = 1`` - If the connection is HTTPS, validate the certificate and hostname. - -``ca_certs = [raven]/data/cacert.pem`` - A certificate bundle to use when validating SSL connections. - -For example, to increase the timeout and to disable SSL verification:: - - SENTRY_DSN = '___DSN___?timeout=5&verify_ssl=0' - - -Eventlet --------- - -Should only be used within an Eventlet IO loop. - -.. code-block:: python - - from raven.transport.eventlet import EventletHTTPTransport - - Client('...', transport=EventletHTTPTransport) - - -Gevent ------- - -Should only be used within a Gevent IO loop. - -.. code-block:: python - - from raven.transport.gevent import GeventedHTTPTransport - - Client('...', transport=GeventedHTTPTransport) - - -Requests --------- - -Requires the ``requests`` library. Synchronous. - -.. code-block:: python - - from raven.transport.requests import RequestsHTTPTransport - - Client('...', transport=RequestsHTTPTransport) - -Alternatively, a threaded client also exists for Requests: - -.. code-block:: python - - from raven.transport.threaded_requests import ThreadedRequestsHTTPTransport - - Client('...', transport=ThreadedRequestsHTTPTransport) - - -Sync ----- - -A synchronous blocking transport. - -.. code-block:: python - - from raven.transport.http import HTTPTransport - - Client('...', transport=HTTPTransport) - - -Threaded (Default) ------------------- - -Spawns an async worker for processing messages. - -.. code-block:: python - - from raven.transport.threaded import ThreadedHTTPTransport - - Client('...', transport=ThreadedHTTPTransport) - - -Tornado -------- - -Should only be used within a Tornado IO loop. - -.. code-block:: python - - from raven.transport.tornado import TornadoHTTPTransport - - Client('...', transport=TornadoHTTPTransport) - - -Twisted -------- - -Should only be used within a Twisted event loop. - -.. code-block:: python - - from raven.transport.twisted import TwistedHTTPTransport - - Client('...', transport=TwistedHTTPTransport) diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index 28a1c54..0000000 --- a/docs/usage.rst +++ /dev/null @@ -1,110 +0,0 @@ -Basic Usage -=========== - -This gives a basic overview of how to use the raven client with Python -directly. - -Capture an Error ----------------- - -The most basic use for raven is to record one specific error that occurs:: - - from raven import Client - - client = Client('___DSN___') - - try: - 1 / 0 - except ZeroDivisionError: - client.captureException() - -Reporting an Event ------------------- - -To report an arbitrary event you can use the -:py:meth:`~raven.Client.capture` method. This is the most low-level -method available. In most cases you would want to use the -:py:meth:`~raven.Client.captureMessage` method instead however which -directly reports a message:: - - client.captureMessage('Something went fundamentally wrong') - - -Adding Context --------------- - -The raven client internally keeps a thread local mapping that can carry -additional information. Whenever a message is submitted to Sentry that -additional data will be passed along. - -For instance if you use a web framework, you can use this to inject -additional information into the context. The basic primitive for this is -the :py:attr:`~raven.Client.context` attribute. It provides a `merge()` -and `clear()` function that can be used:: - - def handle_request(request): - client.context.merge({'user': { - 'email': request.user.email - }}) - try: - ... - finally: - client.context.clear() - -Additionally starting with Raven 5.14 you can bind the context to the -current thread to enable crumb support by calling `activate()`. The -deactivation happens upon calling `clear()`. This can also be achieved by -using the context object with the `with` statement. This is needed to -enable breadcrumb capturing. Framework integrations typically do this -automatically. - -These two examples are equivalent:: - - def handle_request(request): - client.context.activate() - client.context.merge({'user': { - 'email': request.user.email - }}) - try: - ... - finally: - client.context.clear() - -With a context manager:: - - def handle_request(request): - with client.context: - client.context.merge({'user': { - 'email': request.user.email - }}) - try: - ... - finally: - client.context.clear() - -Testing the Client ------------------- - -Once you've got your server configured, you can test the Raven client by -using its CLI:: - - raven test ___DSN___ - -If you've configured your environment to have ``SENTRY_DSN`` available, you -can simply drop the optional DSN argument:: - - raven test - -You should get something like the following, assuming you're configured everything correctly:: - - $ raven test sync+___DSN___ - Using DSN configuration: - sync+___DSN___ - - Client configuration: - servers : ___API_URL___/api/store/ - project : ___PROJECT_ID___ - public_key : ___PUBLIC_KEY___ - secret_key : ___SECRET_KEY___ - - Sending a test message... success! @@ -1,7 +1,7 @@ [tool:pytest] python_files=test*.py addopts=--tb=native -p no:doctest -p no:logging --cov=raven -norecursedirs=raven build bin dist docs htmlcov hooks node_modules .* {args} +norecursedirs=raven build bin dist htmlcov hooks node_modules .* {args} DJANGO_SETTINGS_MODULE = tests.contrib.django.settings python_paths = tests flake8-ignore = @@ -10,7 +10,7 @@ flake8-ignore = [flake8] ignore = F999,E501,E128,E124,E402,W503,E731,F841,D100,D101,D102,D103,D104,D105,D107,D200,D201,D205,D400,D401,D402,D403,I100,I101, I201, I202 max-line-length = 100 -exclude = .tox,.git,docs,tests +exclude = .tox,.git,tests [bdist_wheel] universal = 1 @@ -98,15 +98,6 @@ deps = commands = pylint raven/ setup.py -[testenv:doc8] -basepython = python3.5 -skip_install = true -deps = - sphinx - doc8 -commands = - doc8 docs/ - [testenv:bandit] basepython = python3.5 @@ -122,13 +113,11 @@ skip_install = true deps = {[testenv:flake8]deps} {[testenv:pylint]deps} - {[testenv:doc8]deps} {[testenv:readme]deps} {[testenv:bandit]deps} commands = {[testenv:flake8]commands} {[testenv:pylint]commands} - {[testenv:doc8]commands} {[testenv:readme]commands} {[testenv:bandit]commands} |
