Sentry's documentation (and tools to build it)
Home Page: https://docs.sentry.io
License: Other
Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoying technology. If you want to join us Check out our open positions
Take a look at our Contributing to Docs documentation to get started.
Note: The documentation for this repository is self-hosted via src/docs/contributing/.
This is the Next.js version of our docs.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
The Cordova docs are live, but we should make sure it's surfaced in the sidebar.
This is the subticket for getsentry/sentry#2899.
Some kind of message letting people know that a client is not considered production quality/full featured.
i.e. raven-objc
On our Angular2 integration page: https://docs.sentry.io/clients/javascript/integrations/angular/
It looks like the words "angular/core/ErrorHandler" link to: https://angular.io/docs/js/latest/api/core/index/ErrorHandler-class
It would appear that the correct link should be: https://angular.io/api/core/ErrorHandler
We currently do not see when the doc builder fails. We can hook it up with sentry easily though.
This is a quick overview issue about the wizard functionality:
Wizards are a basic overview of how to configure a client or integration for a sentry project. Just the bare minimums for copy/paste.
Wizards are configured in a sentry-doc-config.json file. There can be multiple wizards per such a file and those files can appear in any folder in the documentation tree. The contents are as follows:
{
// all wizards go here
"wizards": {
// the key is the id of the wizard which is how sentry can identify it.
"python": {
// the human readable name for this wizard. This should be the name
// of the programming language of framework.
"name": "Python",
// the most appropriate name of the client lib used
"client_lib": "raven-python",
// this is true if the wizard refers to a framework or app rather than a raw client.
"is_framework": false,
// the name of the document (can be relative) the documentation should
// link to.
"doc_link": "installation",
// a list of selectors that should be included in the wizard. This just
// points to `rst_file#headline_anchor`.
"snippets": [
"installation#installation",
"usage#capture-an-error",
"usage#reporting-an-event"
]
}
}The docs build them out automatically. They are then placed in a _wizards folder as JSON file. The server can either load that directly from the docs or we can ship it.
Get the remaining core platforms onto the new docs:
When doing make build, it fails with the following output:
[2016-01-14 15:09:16] redis: Launching redis server
[ERROR] Unable to fetch internal project
Traceback (most recent call last):
File "./doc-modules/sentry/src/sentry/utils/raven.py", line 59, in send
project = Project.objects.get_from_cache(id=settings.SENTRY_PROJECT)
File "./doc-modules/sentry/src/sentry/db/models/manager.py", line 259, in get_from_cache
result = self.get(**kwargs)
File "/usr/local/lib/python2.7/site-packages/django/db/models/manager.py", line 151, in get
return self.get_queryset().get(*args, **kwargs)
File "/usr/local/lib/python2.7/site-packages/django/db/models/query.py", line 304, in get
num = len(clone)
File "/usr/local/lib/python2.7/site-packages/django/db/models/query.py", line 77, in __len__
self._fetch_all()
File "/usr/local/lib/python2.7/site-packages/django/db/models/query.py", line 857, in _fetch_all
self._result_cache = list(self.iterator())
File "/usr/local/lib/python2.7/site-packages/django/db/models/query.py", line 220, in iterator
for row in compiler.results_iter():
File "/usr/local/lib/python2.7/site-packages/django/db/models/sql/compiler.py", line 713, in results_iter
for rows in self.execute_sql(MULTI):
File "/usr/local/lib/python2.7/site-packages/django/db/models/sql/compiler.py", line 786, in execute_sql
cursor.execute(sql, params)
File "/usr/local/lib/python2.7/site-packages/django/db/backends/util.py", line 69, in execute
return super(CursorDebugWrapper, self).execute(sql, params)
File "/usr/local/lib/python2.7/site-packages/django/db/backends/util.py", line 53, in execute
return self.cursor.execute(sql, params)
File "/usr/local/lib/python2.7/site-packages/django/db/utils.py", line 99, in __exit__
six.reraise(dj_exc_type, dj_exc_value, traceback)
File "/usr/local/lib/python2.7/site-packages/django/db/backends/util.py", line 53, in execute
return self.cursor.execute(sql, params)
File "/usr/local/lib/python2.7/site-packages/django/db/backends/sqlite3/base.py", line 452, in execute
return Database.Cursor.execute(self, query, params)
OperationalError: no such table: sentry_project
Traceback (most recent call last):
File "./bin/../doc-modules/sentry/api-docs/generator.py", line 218, in <module>
cli()
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 716, in __call__
return self.main(*args, **kwargs)
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 696, in main
rv = self.invoke(ctx)
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 889, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 534, in invoke
return callback(*args, **kwargs)
File "./bin/../doc-modules/sentry/api-docs/generator.py", line 154, in cli
with SentryBox():
File "./bin/../doc-modules/sentry/api-docs/generator.py", line 112, in __enter__
self.redis = launch_redis()
File "./bin/../doc-modules/sentry/api-docs/generator.py", line 56, in launch_redis
cl = Popen(['redis-server', '-'], stdin=PIPE, stdout=open(os.devnull, 'r+'))
File "/usr/local/Cellar/python/2.7.11/Frameworks/Python.framework/Versions/2.7/lib/python2.7/subprocess.py", line 710, in __init__
errread, errwrite)
File "/usr/local/Cellar/python/2.7.11/Frameworks/Python.framework/Versions/2.7/lib/python2.7/subprocess.py", line 1335, in _execute_child
raise child_exception
OSError: [Errno 2] No such file or directory
--> Generate API documentation
./bin/generate-api-docs
Traceback (most recent call last):
File "./bin/generate-api-docs", line 165, in <module>
cli()
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 716, in __call__
return self.main(*args, **kwargs)
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 696, in main
rv = self.invoke(ctx)
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 889, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python2.7/site-packages/click/core.py", line 534, in invoke
return callback(*args, **kwargs)
File "./bin/generate-api-docs", line 156, in cli
for section in iter_sections():
File "./bin/generate-api-docs", line 42, in iter_sections
with open(os.path.join(API_CACHE, 'sections.json')) as f:
IOError: [Errno 2] No such file or directory: './docs/_apicache/sections.json'
Makefile:56: recipe for target 'generate-api-docs' failed
make: *** [generate-api-docs] Error 1
Why is redis required to build the documentation? What's going on here?
In "choose project" dialog I can select projects of teams in my organization in which I'm not participating, and can't see in Sentry app.
Proposal to overhaul docs to be more unified, and friendly to new users.
e.g. https://docs.mesosphere.com/
A few notes:
sphinx and click need to be pip installed manually. somehow make build doesn't do the trick.
How to use?
Is it enabled for all users?
Pre-requisites?
Regarding Minidump: You can upload minidump file on to Sentry, which will create a event. To find the correct minidump endpoint, go to [Organization] » [Project] » Project Settings » Client Keys (DSN) » Details and then scroll down to Minidump Endpoint. See attached screenshot for example. (TODO: figure out if it is enabled for each user). To use: Send POST request to endpoint, with ‘Content-Type: multipart/form-data’ and upload_file_minidump referencing the file. See: https://github.com/getsentry/sentry/blob/f0ac91f2ec6b45ad18e5eea6df72c5c72573e964/src/sentry/web/api.py#L548-L551 and https://github.com/getsentry/sentry/blob/f0ac91f2ec6b45ad18e5eea6df72c5c72573e964/src/sentry/web/api.py#L507
Lets move the "server" docs (i.e. installation) into its own subheading in the nav bar, below integrations.
Opening for discussion. I found the docs for Rails configuration a bit confusing. https://docs.sentry.io/clients/ruby/integrations/rails/#configuration
A new Rails app in recent versions (I tested 4.2.8 and 5.1), the default settings for config.config.action_dispatch.show_exceptions are set to true, so I don't understand the comment in the code snippet from the docs:
config.action_dispatch.show_exceptions = false # this is the default setting in production
I could be mistaken but I believe, unless developers have control over their web server configuration settings, a consequence of setting this value to false could be that pretty error pages are no longer served in production environments. This would happen for vanilla Rails apps on Heroku, for example. This may not be common knowledge, so perhaps a note or even a sample web server configuration would be helpful.
I'm also not sure whether this config change is even necessary depending on the version of the sentry and rails gems being used.
Or... am I missing something?
We need to more clearly split DSNs by organization, and improve visibility when you're scrolling (and not using typeahead).
The header should render statically for the most part.
We can pull in the authenticated user post-load, but the logo/basic nav can be hardcoded.
If PostgreSQL isn't installed, make build fails with the following output:
Collecting psycopg2<2.6.0,>=2.5.0 (from sentry[dev])
Using cached psycopg2-2.5.5.tar.gz
Complete output from command python setup.py egg_info:
running egg_info
creating pip-egg-info/psycopg2.egg-info
writing pip-egg-info/psycopg2.egg-info/PKG-INFO
writing top-level names to pip-egg-info/psycopg2.egg-info/top_level.txt
writing dependency_links to pip-egg-info/psycopg2.egg-info/dependency_links.txt
writing manifest file 'pip-egg-info/psycopg2.egg-info/SOURCES.txt'
warning: manifest_maker: standard file '-c' not found
Error: pg_config executable not found.
Please add the directory containing pg_config to the PATH
or specify the full executable path with the option:
python setup.py build_ext --pg-config /path/to/pg_config build ...
or with the pg_config option in 'setup.cfg'.
----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /private/var/folders/_t/hkn5jvjd6blcf9tf8zv5cx8c0000gn/T/pip-build-ePGMVA/psycopg2
Traceback (most recent call last):
File "./bin/../doc-modules/sentry/api-docs/generator.py", line 6, in <module>
import click
ImportError: No module named click
Traceback (most recent call last):
File "./bin/../doc-modules/sentry/bin/dump-command-help", line 3, in <module>
import click
ImportError: No module named click
Makefile:52: recipe for target 'extract-docs' failed
make: *** [extract-docs] Error 1
Why would building documentation require PostgreSQL? Doing brew install postgresql fixed that part of the build (though it failed for another reason later), but it would be nice not requiring PostgreSQL just to convert some .rst files to HTML.
Rename this in remaining places
Installing via pip has a dependency to libpq-dev (debian/ubuntu), which is not listed on the "Installation with python" page.
https://docs.getsentry.com/hosted/clients/php/
IMHO this page should be an anchors list, not separate page, so I continuously read whole php guide.
Or subpages like this should have a footer with link on next page in section (Installation => Usage => Configuration)
Another good idea is to sepparate section nav (php client) from whole docs nav and move it to the right.
Nice new docs tho! 👍
They're not generally useful, so lets stuff them in the footer. Search itself can be a search bar that we had implemented somewhere.
Further to a conversation on IRC. As SSO is not publicly supported (i.e. commercial), the documentation on SSO should make that clear to avoid people fruitlessly following the instructions.
e.g. https://docs.getsentry.com/hosted/clients/javascript/sourcemaps/#uploading-source-maps-to-sentry
This is what you see (header "Uploading Source Maps to Sentry" is missing):
https://www.dropbox.com/s/8s4u6c0ipe92tkh/Screenshot%202015-10-31%2017.02.38.png?dl
Should be:
I recently wanted to add environment and release data to my csp reports.
I found by experimentation and a little IRC help, /csp-report?sentry_release=... is supported but /csp-report?sentry_environment=... is not (yet).
Long story short, please document the security report endpoints, indicating what meta parameters are supported and how.
Thanks!
👋 Sentry,
Your tool is so great. I was using your documentation and I felt like the search experience could be way much better:
I am working on DocSearch, The easiest way to add search to your documentation. I couldn't help providing you such free and nice tool:
Congratulations, your search is now ready!
I've successfully configured the underlying crawler and it will now run every 24h.
You're now a few steps away from having it working on your website:
<!-- at the end of the HEAD -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
<!-- at the end of the BODY -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
apiKey: 'afa63b18ba7e71185819b923f51bbbec',
indexName: 'sentry',
inputSelector: '### REPLACE ME ####',
debug: false // Set debug to true if you want to inspect the dropdown
});
</script>Add a search input in your page if you don't have any yet. Then update the inputSelector value in JS snippet to a CSS selector that targets your search input field.
Replace $CLIENT with the client you want to search on. The list of possible client is hardcode in the config.
So as of today you have: cocoa, cordova, csharp, elixir, go, java, javascript, node, perl, php, python, react-native, ruby
For example if you want to refine the search to the client "cocoa" just specify: 'facetFilters': ["client:cocoa"]
Please open a pull request if want to leverage your configuration!
Feel free to get back to us if you have any issues or questions regarding the integration.
We'd also be happy to get your feedback and thoughts about DocSearch - so we can continue to improve it.
Have a nice day :)
The instructions explaining how to enable user feedback for Django do not work. Django passes an empty context to the 500.html template. So the user feedback form is never shown because the required request.sentry.id variable is missing.
django.views.defaults.server_error() calls template.render() with no arguments:
@requires_csrf_token
def server_error(request, template_name=ERROR_500_TEMPLATE_NAME):
"""
500 error handler.
Templates: :template:`500.html`
Context: None
"""
try:
template = loader.get_template(template_name)
except TemplateDoesNotExist:
if template_name != ERROR_500_TEMPLATE_NAME:
# Reraise if it's a missing custom template.
raise
return http.HttpResponseServerError('<h1>Server Error (500)</h1>', content_type='text/html')
return http.HttpResponseServerError(template.render())Looking at the code of django.template.backends.django.Template.render() and django.template.context.make_context() shows that in this case just an empty context is returned:
class DjangoTemplates(BaseEngine):
# ...
def render(self, context=None, request=None):
context = make_context(context, request, autoescape=self.backend.engine.autoescape)
try:
return self.template.render(context)
except TemplateDoesNotExist as exc:
reraise(exc, self.backend)def make_context(context, request=None, **kwargs):
"""
Create a suitable Context from a plain dict and optionally an HttpRequest.
"""
if context is not None and not isinstance(context, dict):
raise TypeError('context must be a dict rather than %s.' % context.__class__.__name__)
if request is None:
context = Context(context, **kwargs)
else:
# The following pattern is required to ensure values from
# context override those from template context processors.
original_context = context
context = RequestContext(request, **kwargs)
if original_context:
context.push(original_context)
return contextCreating the HttpResponseServerError with a custom server_error() view like this solves the problem:
@requires_csrf_token
def server_error(request, template_name=ERROR_500_TEMPLATE_NAME):
"""500 error handler using RequestContext."""
try:
template = loader.get_template(template_name)
except TemplateDoesNotExist:
if template_name != ERROR_500_TEMPLATE_NAME:
# Reraise if it's a missing custom template.
raise
return http.HttpResponseServerError('<h1>Server Error (500)</h1>', content_type='text/html')
return http.HttpResponseServerError(template.render(None, request))Currently the installation with docker page: https://docs.getsentry.com/on-premise/server/installation/docker/
says
On top of that, we have a requirements.txt file for installing plugins.
and links to
https://docs.getsentry.com/on-premise/server/plugins/
which does not explain how to use the requirements.txt file for installing plugins. It would be ideal to have an example that explained how to install plugins and pin versions.
For the javascript docs we need to find a new solution for how to reference the right version of the cdn files (version number etc.)
Ideally we could embed what's currently on ravenjs.com directly into the docs.
Just says "Python" or "Django".
Maybe "PLATFORM – Sentry Documentation"?
Sentry supports a ton of functionality and now that we do a pass over the docs we need to decide what is the minimum set we want to document, and then make sure all libraries support that and the protocol docs match.
This might cover:
I've setup Sentry-Cli and by default it gives us a bunch of great information:
I'm able to add my own "extra data" or "tags" as described here.
But now I've received a request to update user, family, and device model.
I'm reading through the documentation but I don't see anything. Is this possible?
Since the dev servers and the test environnement is on linux, it would be nice to add the instructions for linux too. Latest Ubuntu would be fine I think.
I guess, you could just add a link to the official installation from source process.
I can make a PR if this issue is confirmed.
Currently the docker installation still works with containers that are being linked together, this practice is currently heavily outdated as suggested by docker itself:
Warning: The --link flag is a deprecated legacy feature of Docker.
https://docs.sentry.io/server/installation/docker/
Could the docs be updated to preferably use a compose file? I have seen quite a lot of examples to get this done.
If there is another reason why this is not being done I would love to know why. Otherwise I would be happy to help get this started.
Document the behavior of Merge and Similar Issues.
I noticed recently that raven now wraps up all the console methods, but I do not see any documentation that describes why? or how it could possibly be useful? Has anyone come across this yet and could point me to some documentation on its use?
the issue I come across is I can no longer do simple debugging with console.log() .. the source becomes raven.js and i can no longer track where in my code it is eminating from?
pulled version information from 'sentry' module
building assets for Sentry v8.5.0.dev0 (build UNKNOWN)
Could not determine sentry version or build
Cleaning up...
Command /home/sentry/sentry-docs/.api-docs-venv/bin/python -c "import setuptools, tokenize;file='/home/sentry/sentry-docs/.api-docs-venv/build/sentry/setup.py';exec(compile(getattr(tokenize, 'open', open)(file).read().replace('\r\n', '\n'), file, 'exec'))" install --record /tmp/pip-7H0A0_-record/install-record.txt --single-version-externally-managed --compile --install-headers /home/sentry/sentry-docs/.api-docs-venv/include/site/python2.7 failed with error code 1 in /home/sentry/sentry-docs/.api-docs-venv/build/sentry
Storing debug log for failure in /home/sentry/.pip/pip.log
Traceback (most recent call last):
File "/home/sentry/sentry-docs/bin/../doc-modules/sentry/api-docs/generator.py", line 19, in
from sentry.runner import configure
ImportError: No module named sentry.runner
Traceback (most recent call last):
File "/home/sentry/sentry-docs/bin/../doc-modules/sentry/bin/dump-command-help", line 6, in
from sentry.runner import cli as root_command
ImportError: No module named sentry.runner
make: *** [extract-docs] Error 1
sentry@iZ28sbg9kgvZ:~/sentry-docs$
Right now it's fairly confusing how things work.
For example:
One solution that seems reasonable would be to move the project selector so that:
Somehow this must be possible. Let's see if we can use all the CPUs so doc builds take less time.
Hi,
I started the api documentation by API authentification https://docs.sentry.io/api/auth/#
And I get a 404 on the first example $ curl -H 'Authorization: Bearer {TOKEN}' https://sentry.io/api/0/projects/1/
The trailing 1/ is causing the problem.
The example should be $ curl -H 'Authorization: Bearer {TOKEN}' https://sentry.io/api/0/projects/
A description of what client docs should look like (rough layout) and requirements.
Some examples:
When clicking a link on the nav bar, you lose your place on page load.
When clicking a link on the nav bar, we should scroll the active section's nav bar element into view.
make requirements && make build as per the instructions installs a full sentry, runs test, and then finally doesn't produce anything:
(py27) [whopper:~/dev/sentry-all/sentry-docs] $ bin/web
bin/web: line 3: cd: build/html: No such file or directory
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.