From 7def7fba2cec10a7185809c5a1980efe9ea9356b Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 17:00:00 -0800 Subject: [PATCH 01/12] refactor namespace package - cleanup samples --- .../opencensus-ext-django/examples}/app/__init__.py | 0 .../opencensus-ext-django/examples}/app/forms.py | 0 .../opencensus-ext-django/examples}/app/settings.py | 0 .../opencensus-ext-django/examples}/app/templates/home.html | 0 .../opencensus-ext-django/examples}/app/urls.py | 0 .../opencensus-ext-django/examples}/app/views.py | 0 .../django => contrib/opencensus-ext-django/examples}/manage.py | 0 contrib/opencensus-ext-django/setup.py | 2 +- .../flask => contrib/opencensus-ext-flask/examples}/custom.py | 0 .../flask => contrib/opencensus-ext-flask/examples}/simple.py | 0 contrib/opencensus-ext-flask/setup.py | 2 +- .../opencensus-ext-grpc/examples}/hello_world.proto | 0 .../opencensus-ext-grpc/examples}/hello_world_client.py | 0 .../opencensus-ext-grpc/examples}/hello_world_pb2.py | 0 .../opencensus-ext-grpc/examples}/hello_world_pb2_grpc.py | 0 .../opencensus-ext-grpc/examples}/hello_world_server.py | 0 contrib/opencensus-ext-grpc/setup.py | 2 +- .../opencensus-ext-pyramid/examples}/__init__.py | 0 .../opencensus-ext-pyramid/examples}/app/__init__.py | 0 .../opencensus-ext-pyramid/examples}/simple.py | 0 contrib/opencensus-ext-pyramid/setup.py | 2 +- setup.py | 1 - 22 files changed, 4 insertions(+), 5 deletions(-) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/app/__init__.py (100%) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/app/forms.py (100%) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/app/settings.py (100%) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/app/templates/home.html (100%) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/app/urls.py (100%) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/app/views.py (100%) rename {examples/trace/helloworld/django => contrib/opencensus-ext-django/examples}/manage.py (100%) mode change 100755 => 100644 rename {examples/trace/helloworld/flask => contrib/opencensus-ext-flask/examples}/custom.py (100%) rename {examples/trace/helloworld/flask => contrib/opencensus-ext-flask/examples}/simple.py (100%) rename {examples/trace/grpc => contrib/opencensus-ext-grpc/examples}/hello_world.proto (100%) rename {examples/trace/grpc => contrib/opencensus-ext-grpc/examples}/hello_world_client.py (100%) rename {examples/trace/grpc => contrib/opencensus-ext-grpc/examples}/hello_world_pb2.py (100%) rename {examples/trace/grpc => contrib/opencensus-ext-grpc/examples}/hello_world_pb2_grpc.py (100%) rename {examples/trace/grpc => contrib/opencensus-ext-grpc/examples}/hello_world_server.py (100%) rename {examples/trace/helloworld/pyramid => contrib/opencensus-ext-pyramid/examples}/__init__.py (100%) rename {examples/trace/helloworld/pyramid => contrib/opencensus-ext-pyramid/examples}/app/__init__.py (100%) rename {examples/trace/helloworld/pyramid => contrib/opencensus-ext-pyramid/examples}/simple.py (100%) diff --git a/examples/trace/helloworld/django/app/__init__.py b/contrib/opencensus-ext-django/examples/app/__init__.py similarity index 100% rename from examples/trace/helloworld/django/app/__init__.py rename to contrib/opencensus-ext-django/examples/app/__init__.py diff --git a/examples/trace/helloworld/django/app/forms.py b/contrib/opencensus-ext-django/examples/app/forms.py similarity index 100% rename from examples/trace/helloworld/django/app/forms.py rename to contrib/opencensus-ext-django/examples/app/forms.py diff --git a/examples/trace/helloworld/django/app/settings.py b/contrib/opencensus-ext-django/examples/app/settings.py similarity index 100% rename from examples/trace/helloworld/django/app/settings.py rename to contrib/opencensus-ext-django/examples/app/settings.py diff --git a/examples/trace/helloworld/django/app/templates/home.html b/contrib/opencensus-ext-django/examples/app/templates/home.html similarity index 100% rename from examples/trace/helloworld/django/app/templates/home.html rename to contrib/opencensus-ext-django/examples/app/templates/home.html diff --git a/examples/trace/helloworld/django/app/urls.py b/contrib/opencensus-ext-django/examples/app/urls.py similarity index 100% rename from examples/trace/helloworld/django/app/urls.py rename to contrib/opencensus-ext-django/examples/app/urls.py diff --git a/examples/trace/helloworld/django/app/views.py b/contrib/opencensus-ext-django/examples/app/views.py similarity index 100% rename from examples/trace/helloworld/django/app/views.py rename to contrib/opencensus-ext-django/examples/app/views.py diff --git a/examples/trace/helloworld/django/manage.py b/contrib/opencensus-ext-django/examples/manage.py old mode 100755 new mode 100644 similarity index 100% rename from examples/trace/helloworld/django/manage.py rename to contrib/opencensus-ext-django/examples/manage.py diff --git a/contrib/opencensus-ext-django/setup.py b/contrib/opencensus-ext-django/setup.py index 86e7b717a..333564ad2 100644 --- a/contrib/opencensus-ext-django/setup.py +++ b/contrib/opencensus-ext-django/setup.py @@ -44,7 +44,7 @@ ], extras_require={}, license='Apache-2.0', - packages=find_packages(exclude=('tests',)), + packages=find_packages(exclude=('examples', 'tests',)), namespace_packages=[], url='https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-django', zip_safe=False, diff --git a/examples/trace/helloworld/flask/custom.py b/contrib/opencensus-ext-flask/examples/custom.py similarity index 100% rename from examples/trace/helloworld/flask/custom.py rename to contrib/opencensus-ext-flask/examples/custom.py diff --git a/examples/trace/helloworld/flask/simple.py b/contrib/opencensus-ext-flask/examples/simple.py similarity index 100% rename from examples/trace/helloworld/flask/simple.py rename to contrib/opencensus-ext-flask/examples/simple.py diff --git a/contrib/opencensus-ext-flask/setup.py b/contrib/opencensus-ext-flask/setup.py index fbdf1a756..be5513c26 100644 --- a/contrib/opencensus-ext-flask/setup.py +++ b/contrib/opencensus-ext-flask/setup.py @@ -44,7 +44,7 @@ ], extras_require={}, license='Apache-2.0', - packages=find_packages(exclude=('tests',)), + packages=find_packages(exclude=('examples', 'tests',)), namespace_packages=[], url='https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-flask', zip_safe=False, diff --git a/examples/trace/grpc/hello_world.proto b/contrib/opencensus-ext-grpc/examples/hello_world.proto similarity index 100% rename from examples/trace/grpc/hello_world.proto rename to contrib/opencensus-ext-grpc/examples/hello_world.proto diff --git a/examples/trace/grpc/hello_world_client.py b/contrib/opencensus-ext-grpc/examples/hello_world_client.py similarity index 100% rename from examples/trace/grpc/hello_world_client.py rename to contrib/opencensus-ext-grpc/examples/hello_world_client.py diff --git a/examples/trace/grpc/hello_world_pb2.py b/contrib/opencensus-ext-grpc/examples/hello_world_pb2.py similarity index 100% rename from examples/trace/grpc/hello_world_pb2.py rename to contrib/opencensus-ext-grpc/examples/hello_world_pb2.py diff --git a/examples/trace/grpc/hello_world_pb2_grpc.py b/contrib/opencensus-ext-grpc/examples/hello_world_pb2_grpc.py similarity index 100% rename from examples/trace/grpc/hello_world_pb2_grpc.py rename to contrib/opencensus-ext-grpc/examples/hello_world_pb2_grpc.py diff --git a/examples/trace/grpc/hello_world_server.py b/contrib/opencensus-ext-grpc/examples/hello_world_server.py similarity index 100% rename from examples/trace/grpc/hello_world_server.py rename to contrib/opencensus-ext-grpc/examples/hello_world_server.py diff --git a/contrib/opencensus-ext-grpc/setup.py b/contrib/opencensus-ext-grpc/setup.py index 551a1e826..1193f50c5 100644 --- a/contrib/opencensus-ext-grpc/setup.py +++ b/contrib/opencensus-ext-grpc/setup.py @@ -44,7 +44,7 @@ ], extras_require={}, license='Apache-2.0', - packages=find_packages(exclude=('tests',)), + packages=find_packages(exclude=('examples', 'tests',)), namespace_packages=[], url='https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-grpc', zip_safe=False, diff --git a/examples/trace/helloworld/pyramid/__init__.py b/contrib/opencensus-ext-pyramid/examples/__init__.py similarity index 100% rename from examples/trace/helloworld/pyramid/__init__.py rename to contrib/opencensus-ext-pyramid/examples/__init__.py diff --git a/examples/trace/helloworld/pyramid/app/__init__.py b/contrib/opencensus-ext-pyramid/examples/app/__init__.py similarity index 100% rename from examples/trace/helloworld/pyramid/app/__init__.py rename to contrib/opencensus-ext-pyramid/examples/app/__init__.py diff --git a/examples/trace/helloworld/pyramid/simple.py b/contrib/opencensus-ext-pyramid/examples/simple.py similarity index 100% rename from examples/trace/helloworld/pyramid/simple.py rename to contrib/opencensus-ext-pyramid/examples/simple.py diff --git a/contrib/opencensus-ext-pyramid/setup.py b/contrib/opencensus-ext-pyramid/setup.py index 5a2f9ce74..978b36317 100644 --- a/contrib/opencensus-ext-pyramid/setup.py +++ b/contrib/opencensus-ext-pyramid/setup.py @@ -44,7 +44,7 @@ ], extras_require={}, license='Apache-2.0', - packages=find_packages(exclude=('tests',)), + packages=find_packages(exclude=('examples', 'tests',)), namespace_packages=[], url='https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pyramid', zip_safe=False, diff --git a/setup.py b/setup.py index 0196efb48..2c4e881d7 100644 --- a/setup.py +++ b/setup.py @@ -20,7 +20,6 @@ extras = { 'prometheus_client': ['prometheus_client==0.3.1'], - 'requests': ['wrapt==1.10.11'], 'stackdriver': ['google-cloud-trace>=0.20.1, <0.30'], } From 6baf1ec19e72545d0dcc5fa58b30d5575e638a51 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 17:07:43 -0800 Subject: [PATCH 02/12] remove wrapt from test dependencies --- requirements-test.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements-test.txt b/requirements-test.txt index d272a446e..e632ea5b4 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -7,6 +7,5 @@ pytest==3.2.2 pytest-cov==2.5.1 retrying==1.3.3 WebOb==1.7.3 -wrapt==1.10.11 thrift==0.10.0 prometheus_client==0.5.0 From 9e2ac8848d7444edf76779cfc0097edd00ada183 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 17:08:57 -0800 Subject: [PATCH 03/12] remove psycopg2 from test dependencies --- requirements-test.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements-test.txt b/requirements-test.txt index e632ea5b4..da8602764 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -2,7 +2,6 @@ google-cloud-monitoring==0.31.0 google-cloud-trace==0.20.1 grpcio==1.16.1 mock==2.0.0 -psycopg2==2.7.3.1 pytest==3.2.2 pytest-cov==2.5.1 retrying==1.3.3 From cbf00729d3289408fe9c19b596eeadaa08069df1 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 17:11:04 -0800 Subject: [PATCH 04/12] remove grpcio from test dependencies --- requirements-test.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements-test.txt b/requirements-test.txt index da8602764..5712829e8 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -1,6 +1,5 @@ google-cloud-monitoring==0.31.0 google-cloud-trace==0.20.1 -grpcio==1.16.1 mock==2.0.0 pytest==3.2.2 pytest-cov==2.5.1 From 6b6d07b257b17dab1febf427d51f00349818383f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 20:41:03 -0800 Subject: [PATCH 05/12] polish README --- README.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index f0b1193ec..f57384615 100644 --- a/README.rst +++ b/README.rst @@ -1,17 +1,18 @@ -OpenCensus for Python - A stats collection and distributed tracing framework +OpenCensus - A stats collection and distributed tracing framework ============================================================================ - `Census`_ for Python. Census provides a framework to measure a server's resource - usage and collect performance stats. This repository contains Python related - utilities and supporting software needed by Census. - - .. _Census: https://github.com/census-instrumentation - |circleci| .. |circleci| image:: https://circleci.com/gh/census-instrumentation/opencensus-python.svg?style=shield :target: https://circleci.com/gh/census-instrumentation/opencensus-python +`OpenCensus`_ for Python. OpenCensus provides a framework to measure a +server's resource usage and collect performance stats. This repository +contains Python related utilities and supporting software needed by +OpenCensus. + +.. _OpenCensus: https://github.com/census-instrumentation + - `API Documentation`_ .. _API Documentation: https://opencensus.io/api/python/trace/usage.html From b1d0f15a73ff749be05590674bdb994c3d7559f5 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 20:46:17 -0800 Subject: [PATCH 06/12] add badge to README --- README.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.rst b/README.rst index f57384615..ff30bcb28 100644 --- a/README.rst +++ b/README.rst @@ -1,10 +1,16 @@ OpenCensus - A stats collection and distributed tracing framework ============================================================================ +|gitter| |circleci| +|pypi| .. |circleci| image:: https://circleci.com/gh/census-instrumentation/opencensus-python.svg?style=shield :target: https://circleci.com/gh/census-instrumentation/opencensus-python +.. |gitter| image: https://badges.gitter.im/census-instrumentation/lobby.svg + :target: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +.. |pypi| image:: https://badge.fury.io/py/opencensus.svg + :target: https://pypi.org/project/opencensus/ `OpenCensus`_ for Python. OpenCensus provides a framework to measure a server's resource usage and collect performance stats. This repository From 81c972f159641e6a25d0bd507b90a26995df48ff Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 5 Mar 2019 20:47:03 -0800 Subject: [PATCH 07/12] fix typo --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index ff30bcb28..bea4ea223 100644 --- a/README.rst +++ b/README.rst @@ -7,7 +7,7 @@ OpenCensus - A stats collection and distributed tracing framework .. |circleci| image:: https://circleci.com/gh/census-instrumentation/opencensus-python.svg?style=shield :target: https://circleci.com/gh/census-instrumentation/opencensus-python -.. |gitter| image: https://badges.gitter.im/census-instrumentation/lobby.svg +.. |gitter| image:: https://badges.gitter.im/census-instrumentation/lobby.svg :target: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge .. |pypi| image:: https://badge.fury.io/py/opencensus.svg :target: https://pypi.org/project/opencensus/ From 0d38883f9bacf9e5ecb2bfdda30a57a497e58c34 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 6 Mar 2019 10:49:38 -0800 Subject: [PATCH 08/12] add dependency link --- setup.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/setup.py b/setup.py index 2c4e881d7..a112de01f 100644 --- a/setup.py +++ b/setup.py @@ -54,5 +54,8 @@ license='Apache-2.0', packages=find_packages(exclude=('tests',)), namespace_packages=[], + dependency_links=[ + 'https://github.com/census-instrumentation/opencensus-python@master#subdirectory=contrib/opencensus-correlation', + ], url='https://github.com/census-instrumentation/opencensus-python', ) From 8052b7d99f0cbd769aa0909e2e786ba9d448ed1f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 6 Mar 2019 12:14:26 -0800 Subject: [PATCH 09/12] Revert "add dependency link" This reverts commit 0d38883f9bacf9e5ecb2bfdda30a57a497e58c34. --- setup.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/setup.py b/setup.py index a112de01f..2c4e881d7 100644 --- a/setup.py +++ b/setup.py @@ -54,8 +54,5 @@ license='Apache-2.0', packages=find_packages(exclude=('tests',)), namespace_packages=[], - dependency_links=[ - 'https://github.com/census-instrumentation/opencensus-python@master#subdirectory=contrib/opencensus-correlation', - ], url='https://github.com/census-instrumentation/opencensus-python', ) From 89aa140f27a51ce756b5c1417188363071d01826 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 6 Mar 2019 13:01:03 -0800 Subject: [PATCH 10/12] polish docs --- README.rst | 252 ++---------------- .../README.rst | 7 + contrib/opencensus-ext-grpc/README.rst | 15 ++ contrib/opencensus-ext-httplib/README.rst | 8 + contrib/opencensus-ext-mysql/README.rst | 5 + contrib/opencensus-ext-postgresql/README.rst | 5 + contrib/opencensus-ext-requests/README.rst | 18 +- contrib/opencensus-ext-sqlalchemy/README.rst | 8 + contrib/opencensus-ext-threading/README.rst | 6 +- 9 files changed, 98 insertions(+), 226 deletions(-) diff --git a/README.rst b/README.rst index bea4ea223..93fbdc092 100644 --- a/README.rst +++ b/README.rst @@ -242,230 +242,36 @@ For Django, you can configure the blacklist in the ``OPENCENSUS_TRACE_PARAMS`` i .. note:: By default, the health check path for the App Engine flexible environment is not traced, but you can turn it on by excluding it from the blacklist setting. -Framework Integration ---------------------- - -Census supports integration with popular web frameworks including Django, -Flask, and Pyramid. When the application receives a HTTP request, the tracer -will automatically generate a span context using the trace information -extracted from the request headers and propagated to the child spans. - -Flask -~~~~~ - -In your application, use the middleware to wrap your app and the -requests will be automatically traced. - -.. code:: python - - from opencensus.trace.ext.flask.flask_middleware import FlaskMiddleware - - app = flask.Flask(__name__) - - # You can also specify the sampler, exporter, propagator in the middleware, - # default is using `AlwaysOnSampler` as sampler, `PrintExporter` as exporter, - # `GoogleCloudFormatPropagator` as propagator. - middleware = FlaskMiddleware(app) - -Django -~~~~~~ - -For tracing Django requests, you will need to add the following line to -the ``MIDDLEWARE_CLASSES`` section in the Django ``settings.py`` file. - -.. code:: python - - MIDDLEWARE_CLASSES = [ - ... - 'opencensus.trace.ext.django.middleware.OpencensusMiddleware', - ] - -And add this line to the ``INSTALLED_APPS`` section: - -.. code:: python - - INSTALLED_APPS = [ - ... - 'opencensus.trace.ext.django', - ] - -You can configure the sampler, exporter, propagator using the ``OPENCENSUS_TRACE`` setting in -``settings.py``: - -.. code:: python - - OPENCENSUS_TRACE = { - 'SAMPLER': 'opencensus.trace.samplers.probability.ProbabilitySampler', - 'EXPORTER': 'opencensus.trace.exporters.print_exporter.PrintExporter', - 'PROPAGATOR': 'opencensus.trace.propagation.google_cloud_format.' - 'GoogleCloudFormatPropagator', - } - -You can configure the sampling rate and other parameters using the ``OPENCENSUS_TRACE_PARAMS`` -setting in ``settings.py``: - -.. code:: python - - OPENCENSUS_TRACE_PARAMS = { - 'BLACKLIST_PATHS': ['/_ah/health'], - 'GCP_EXPORTER_PROJECT': None, - 'SAMPLING_RATE': 0.5, - 'SERVICE_NAME': 'my_service', - 'ZIPKIN_EXPORTER_HOST_NAME': 'localhost', - 'ZIPKIN_EXPORTER_PORT': 9411, - 'ZIPKIN_EXPORTER_PROTOCOL': 'http', - 'JAEGER_EXPORTER_HOST_NAME': None, - 'JAEGER_EXPORTER_PORT': None, - 'JAEGER_EXPORTER_AGENT_HOST_NAME': 'localhost', - 'JAEGER_EXPORTER_AGENT_PORT': 6831 - } - - -Pyramid -~~~~~~~ - -In your application, add the pyramid tween and your requests will be -traced. - -.. code:: python - - def main(global_config, **settings): - config = Configurator(settings=settings) - - config.add_tween('opencensus.trace.ext.pyramid' - '.pyramid_middleware.OpenCensusTweenFactory') - -To configure the sampler, exporter, and propagator, pass the instances -into the pyramid settings - -.. code:: python - - from opencensus.trace.exporters import print_exporter - from opencensus.trace.propagation import google_cloud_format - from opencensus.trace.samplers import probability - - settings = {} - settings['OPENCENSUS_TRACE'] = { - 'EXPORTER': print_exporter.PrintExporter(), - 'SAMPLER': probability.ProbabilitySampler(rate=0.5), - 'PROPAGATOR': google_cloud_format.GoogleCloudFormatPropagator(), - } - - config = Configurator(settings=settings) - -gRPC Integration ----------------- - -OpenCensus provides the implementation of interceptors for both the client side -and server side to instrument the gRPC requests and responses. The client -interceptors are used to create a decorated channel that intercepts client -gRPC calls and server interceptors act as decorators over handlers. - -gRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade -your grpcio to the latest version to use this feature. - -For sample usage, please refer to the hello world example in the examples -directory. - -More information about the gRPC interceptors please see the `proposal`_. - -.. _proposal: https://github.com/mehrdada/proposal/blob/python-interceptors/L13-Python-Interceptors.md - -Service Integration -------------------- - -Opencensus supports integration with various popular outbound services such as -SQL packages, Requests and Google Cloud client libraries. To enable integration -services to census: you will need to pass the list of services to census: - -.. code:: python - - from opencensus.trace import config_integration - from opencensus.trace import tracer as tracer_module - - import mysql.connector - - # Trace both mysql-connection and psycopg2 - integration = ['mysql', 'postgresql'] - - config_integration.trace_integrations(integration) - - -MySQL -~~~~~ - -The integration with MySQL supports the `mysql-connector`_ library and is specified -to ``trace_integrations`` using ``'mysql'``. - -.. _mysql-connector: https://pypi.org/project/mysql-connector - -PostgreSQL -~~~~~~~~~~ - -The integration with PostgreSQL supports the `psycopg2`_ library and is specified -to ``trace_integrations`` using ``'postgresql'``. - -.. _psycopg2: https://pypi.org/project/psycopg2 - - -SQLAlchemy -~~~~~~~~~~ - -You can trace usage of the `sqlalchemy package`_, regardless of the underlying -database, by specifying ``'sqlalchemy'`` to ``trace_integrations``. - -.. _SQLAlchemy package: https://pypi.org/project/SQLAlchemy - -.. note:: If you enable tracing of SQLAlchemy as well as the underlying database - driver, you will get duplicate spans. Instead, just trace SQLAlchemy. - -Requests -~~~~~~~~ - -Census can trace HTTP requests made with the `Requests package`_. The request URL, -method, and status will be collected. - -You can enable Requests integration by specifying ``'requests'`` to ``trace_integrations``. - -It's possible to configure a list of URL you don't want traced. By default the request to exporter -won't be traced. It's configurable by giving an array of hostname/port to the attribute -``blacklist_hostnames`` in OpenCensus context's attributes: - -.. code:: python - - execution_context.set_opencensus_attr('blacklist_hostnames',['hostname:port']) - -Only the hostname must be specified if only the hostname is specified in the URL request. - -.. _Requests package: https://pypi.python.org/pypi/requests - -Httplib -~~~~~~~~ - -Census can trace HTTP requests made with the httplib library. - -You can enable Requests integration by specifying ``'httplib'`` to ``trace_integrations``. - -It's possible to configure a list of URL you don't want traced. See requests integration -for more information. The only difference is that you need to specify hostname and port -every time. - -Google Cloud Client Libraries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Census can trace HTTP and gRPC requests made with the `Cloud client libraries`_. -The request URL, method, and status will be collected. - -You can enable Google Cloud client libraries integration by specifying ``'google_cloud_clientlibs'`` to ``trace_integrations``. - -.. _Cloud client libraries: https://github.com/GoogleCloudPlatform/google-cloud-python#google-cloud-python-client - -Threading -~~~~~~~~~ - -Census can propagate trace across threads when using the Threading package. +Integration +----------- -You can enable Threading integration by specifying ``'threading'`` to ``trace_integrations``. +Census supports integration with popular web frameworks, client libraries and built-in libraries. + +- `Django`_ +- `Flask`_ +- `Google Cloud Client Libraries`_ +- `gRPC`_ +- `httplib`_ +- `MySQL`_ +- `PostgreSQL`_ +- `PyMySQL`_ +- `Pyramid`_ +- `requests`_ +- `SQLAlchemy`_ +- `threading`_ + +.. _Django: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-django +.. _Flask: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-flask +.. _Google Cloud Client Libraries: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-google-cloud-clientlibs +.. _gRPC: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-grpc +.. _httplib: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-httplib +.. _MySQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-mysql +.. _PostgreSQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-postgresql +.. _PyMySQL: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pymysql +.. _Pyramid: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-pyramid +.. _requests: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-requests +.. _SQLAlchemy: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-sqlalchemy +.. _threading: https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-threading ------ Stats diff --git a/contrib/opencensus-ext-google-cloud-clientlibs/README.rst b/contrib/opencensus-ext-google-cloud-clientlibs/README.rst index 14bb7835b..8c3fb8a3d 100644 --- a/contrib/opencensus-ext-google-cloud-clientlibs/README.rst +++ b/contrib/opencensus-ext-google-cloud-clientlibs/README.rst @@ -1,6 +1,13 @@ OpenCensus Google Cloud Client Libraries Integration ============================================================================ +Census can trace HTTP and gRPC requests made with the `Cloud client libraries`_. +The request URL, method, and status will be collected. + +You can enable Google Cloud client libraries integration by specifying ``'google_cloud_clientlibs'`` to ``trace_integrations``. + +.. _Cloud client libraries: https://github.com/GoogleCloudPlatform/google-cloud-python#google-cloud-python-client + Installation ------------ diff --git a/contrib/opencensus-ext-grpc/README.rst b/contrib/opencensus-ext-grpc/README.rst index 46a432409..00597af8d 100644 --- a/contrib/opencensus-ext-grpc/README.rst +++ b/contrib/opencensus-ext-grpc/README.rst @@ -1,6 +1,21 @@ OpenCensus gRPC Integration ============================================================================ +OpenCensus provides the implementation of interceptors for both the client side +and server side to instrument the gRPC requests and responses. The client +interceptors are used to create a decorated channel that intercepts client +gRPC calls and server interceptors act as decorators over handlers. + +gRPC interceptor is a new feature in the grpcio1.8.0 release, please upgrade +your grpcio to the latest version to use this feature. + +For sample usage, please refer to the hello world example in the examples +directory. + +More information about the gRPC interceptors please see the `proposal`_. + +.. _proposal: https://github.com/mehrdada/proposal/blob/python-interceptors/L13-Python-Interceptors.md + Installation ------------ diff --git a/contrib/opencensus-ext-httplib/README.rst b/contrib/opencensus-ext-httplib/README.rst index fe143a39d..3e7029d4b 100644 --- a/contrib/opencensus-ext-httplib/README.rst +++ b/contrib/opencensus-ext-httplib/README.rst @@ -1,6 +1,14 @@ OpenCensus httplib Integration ============================================================================ +Census can trace HTTP requests made with the httplib library. + +You can enable requests integration by specifying ``'httplib'`` to ``trace_integrations``. + +It's possible to configure a list of URL you don't want traced. See requests integration +for more information. The only difference is that you need to specify hostname and port +every time. + Installation ------------ diff --git a/contrib/opencensus-ext-mysql/README.rst b/contrib/opencensus-ext-mysql/README.rst index 9463fcfe0..13cf8486d 100644 --- a/contrib/opencensus-ext-mysql/README.rst +++ b/contrib/opencensus-ext-mysql/README.rst @@ -1,6 +1,11 @@ OpenCensus MySQL Integration ============================================================================ +The integration with MySQL supports the `mysql-connector`_ library and is specified +to ``trace_integrations`` using ``'mysql'``. + +.. _mysql-connector: https://pypi.org/project/mysql-connector + Installation ------------ diff --git a/contrib/opencensus-ext-postgresql/README.rst b/contrib/opencensus-ext-postgresql/README.rst index b052a29da..75aaf4d53 100644 --- a/contrib/opencensus-ext-postgresql/README.rst +++ b/contrib/opencensus-ext-postgresql/README.rst @@ -1,6 +1,11 @@ OpenCensus PostgreSQL Integration ============================================================================ +The integration with PostgreSQL supports the `psycopg2`_ library and is specified +to ``trace_integrations`` using ``'postgresql'``. + +.. _psycopg2: https://pypi.org/project/psycopg2 + Installation ------------ diff --git a/contrib/opencensus-ext-requests/README.rst b/contrib/opencensus-ext-requests/README.rst index acbfb9051..8d9f5c4ba 100644 --- a/contrib/opencensus-ext-requests/README.rst +++ b/contrib/opencensus-ext-requests/README.rst @@ -1,6 +1,19 @@ -OpenCensus Requests Integration +OpenCensus requests Integration ============================================================================ +Census can trace HTTP requests made with the `requests package`_. The request URL, +method, and status will be collected. + +You can enable requests integration by specifying ``'requests'`` to ``trace_integrations``. + +It's possible to configure a list of URL you don't want traced. By default the request to exporter +won't be traced. It's configurable by giving an array of hostname/port to the attribute +``blacklist_hostnames`` in OpenCensus context's attributes: + +Only the hostname must be specified if only the hostname is specified in the URL request. + +.. _Requests package: https://pypi.python.org/pypi/requests + Installation ------------ @@ -13,4 +26,5 @@ Usage .. code:: python - # TBD + execution_context.set_opencensus_attr('blacklist_hostnames',['hostname:port']) + diff --git a/contrib/opencensus-ext-sqlalchemy/README.rst b/contrib/opencensus-ext-sqlalchemy/README.rst index 30ad218d9..370cad2f3 100644 --- a/contrib/opencensus-ext-sqlalchemy/README.rst +++ b/contrib/opencensus-ext-sqlalchemy/README.rst @@ -1,6 +1,14 @@ OpenCensus SQLAlchemy Integration ============================================================================ +You can trace usage of the `sqlalchemy package`_, regardless of the underlying +database, by specifying ``'sqlalchemy'`` to ``trace_integrations``. + +.. _SQLAlchemy package: https://pypi.org/project/SQLAlchemy + +.. note:: If you enable tracing of SQLAlchemy as well as the underlying database + driver, you will get duplicate spans. Instead, just trace SQLAlchemy. + Installation ------------ diff --git a/contrib/opencensus-ext-threading/README.rst b/contrib/opencensus-ext-threading/README.rst index 62c562555..c56cd5344 100644 --- a/contrib/opencensus-ext-threading/README.rst +++ b/contrib/opencensus-ext-threading/README.rst @@ -1,6 +1,10 @@ -OpenCensus Threading Integration +OpenCensus threading Integration ============================================================================ +Census can propagate trace across threads when using the threading package. + +You can enable Threading integration by specifying ``'threading'`` to ``trace_integrations``. + Installation ------------ From 54fe1698179369b0a7a98cd3e76be3354bfc865c Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 6 Mar 2019 13:15:24 -0800 Subject: [PATCH 11/12] rename Census to OpenCensus --- README.rst | 8 ++++---- .../README.rst | 2 +- contrib/opencensus-ext-httplib/README.rst | 2 +- contrib/opencensus-ext-requests/README.rst | 2 +- contrib/opencensus-ext-threading/README.rst | 2 +- docs/trace/usage.rst | 14 +++++++------- setup.py | 2 +- 7 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 93fbdc092..b221760cc 100644 --- a/README.rst +++ b/README.rst @@ -81,7 +81,7 @@ You can collect traces using the ``Tracer`` `context manager`_: with tracer.span(name='span2') as span2: do_something_to_trace() -Census will collect everything within the ``with`` statement as a single span. +OpenCensus will collect everything within the ``with`` statement as a single span. Alternatively, you can explicitly start and end a span: @@ -127,7 +127,7 @@ the traces are printed to stdout in JSON format. Other options include writing to a file, sending to Python logging, or reporting to Stackdriver. -This example shows how to configure Census to save the traces to a +This example shows how to configure OpenCensus to save the traces to a file: .. code:: python @@ -161,7 +161,7 @@ By default, traces are exported synchronously, which introduces latency during your code's execution. To avoid blocking code execution, you can initialize your exporter to use a background thread. -This example shows how to configure Census to use a background thread: +This example shows how to configure OpenCensus to use a background thread: .. code:: python @@ -245,7 +245,7 @@ For Django, you can configure the blacklist in the ``OPENCENSUS_TRACE_PARAMS`` i Integration ----------- -Census supports integration with popular web frameworks, client libraries and built-in libraries. +OpenCensus supports integration with popular web frameworks, client libraries and built-in libraries. - `Django`_ - `Flask`_ diff --git a/contrib/opencensus-ext-google-cloud-clientlibs/README.rst b/contrib/opencensus-ext-google-cloud-clientlibs/README.rst index 8c3fb8a3d..8d61a2d9a 100644 --- a/contrib/opencensus-ext-google-cloud-clientlibs/README.rst +++ b/contrib/opencensus-ext-google-cloud-clientlibs/README.rst @@ -1,7 +1,7 @@ OpenCensus Google Cloud Client Libraries Integration ============================================================================ -Census can trace HTTP and gRPC requests made with the `Cloud client libraries`_. +OpenCensus can trace HTTP and gRPC requests made with the `Cloud client libraries`_. The request URL, method, and status will be collected. You can enable Google Cloud client libraries integration by specifying ``'google_cloud_clientlibs'`` to ``trace_integrations``. diff --git a/contrib/opencensus-ext-httplib/README.rst b/contrib/opencensus-ext-httplib/README.rst index 3e7029d4b..d48feba6c 100644 --- a/contrib/opencensus-ext-httplib/README.rst +++ b/contrib/opencensus-ext-httplib/README.rst @@ -1,7 +1,7 @@ OpenCensus httplib Integration ============================================================================ -Census can trace HTTP requests made with the httplib library. +OpenCensus can trace HTTP requests made with the httplib library. You can enable requests integration by specifying ``'httplib'`` to ``trace_integrations``. diff --git a/contrib/opencensus-ext-requests/README.rst b/contrib/opencensus-ext-requests/README.rst index 8d9f5c4ba..169e593c5 100644 --- a/contrib/opencensus-ext-requests/README.rst +++ b/contrib/opencensus-ext-requests/README.rst @@ -1,7 +1,7 @@ OpenCensus requests Integration ============================================================================ -Census can trace HTTP requests made with the `requests package`_. The request URL, +OpenCensus can trace HTTP requests made with the `requests package`_. The request URL, method, and status will be collected. You can enable requests integration by specifying ``'requests'`` to ``trace_integrations``. diff --git a/contrib/opencensus-ext-threading/README.rst b/contrib/opencensus-ext-threading/README.rst index c56cd5344..fb8317c0a 100644 --- a/contrib/opencensus-ext-threading/README.rst +++ b/contrib/opencensus-ext-threading/README.rst @@ -1,7 +1,7 @@ OpenCensus threading Integration ============================================================================ -Census can propagate trace across threads when using the threading package. +OpenCensus can propagate trace across threads when using the threading package. You can enable Threading integration by specifying ``'threading'`` to ``trace_integrations``. diff --git a/docs/trace/usage.rst b/docs/trace/usage.rst index 6f66864e1..1b0af6d91 100644 --- a/docs/trace/usage.rst +++ b/docs/trace/usage.rst @@ -1,11 +1,11 @@ OpenCensus for Python - A stats collection and distributed tracing framework ============================================================================ - `Census`_ for Python. Census provides a framework to measure a server's resource + `OpenCensus`_ provides a framework to measure a server's resource usage and collect performance stats. This repository contains Python related - utilities and supporting software needed by Census. + utilities and supporting software needed by OpenCensus. - .. _Census: https://github.com/census-instrumentation + .. _OpenCensus: https://github.com/census-instrumentation |circleci| @@ -59,7 +59,7 @@ You can collect traces using the ``Tracer`` `context manager`_: with tracer.span(name='span2') as span2: do_something_to_trace() -Census will collect everything within the ``with`` statement as a single span. +OpenCensus will collect everything within the ``with`` statement as a single span. Alternatively, you can explicitly start and end a span: @@ -105,7 +105,7 @@ the traces are printed to stdout in JSON format. Other options include writing to a file, sending to Python logging, or reporting to Stackdriver. -This example shows how to configure Census to save the traces to a +This example shows how to configure OpenCensus to save the traces to a file: .. code:: python @@ -182,7 +182,7 @@ For Django, you can configure the blacklist in the ``OPENCENSUS_TRACE_PARAMS`` i Framework Integration --------------------- -Census supports integration with popular web frameworks including Django, +OpenCensus supports integration with popular web frameworks including Django, Flask, and Pyramid. When the application receives a HTTP request, the tracer will automatically generate a span context using the trace information extracted from the request headers, and propagated to the child spans. @@ -355,7 +355,7 @@ database, by specifying ``'sqlalchemy'`` to ``trace_integrations``. Requests ~~~~~~~~ -Census can trace HTTP requests made with the `Requests package`_. The request URL, +OpenCensus can trace HTTP requests made with the `Requests package`_. The request URL, method, and status will be collected. You can enable Requests integration by specifying ``'requests'`` to ``trace_integrations``. diff --git a/setup.py b/setup.py index 2c4e881d7..bfdcf5956 100644 --- a/setup.py +++ b/setup.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""A setup module for Open Source Census Instrumentation Library""" +"""A setup module for OpenCensus Instrumentation Library""" from setuptools import find_packages from setuptools import setup From 4a54d52811fa4cc4e7f64c866a79f8119ae41005 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 6 Mar 2019 13:41:00 -0800 Subject: [PATCH 12/12] minor cleanup --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index b221760cc..b49cabe46 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ OpenCensus - A stats collection and distributed tracing framework -============================================================================ +================================================================= |gitter| |circleci|