diff --git a/README.rst b/README.rst index f0b1193ec..b49cabe46 100644 --- a/README.rst +++ b/README.rst @@ -1,16 +1,23 @@ -OpenCensus for Python - 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 +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 +contains Python related utilities and supporting software needed by +OpenCensus. + +.. _OpenCensus: https://github.com/census-instrumentation - `API Documentation`_ @@ -74,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: @@ -120,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 @@ -154,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 @@ -235,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``. +OpenCensus 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/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/contrib/opencensus-ext-google-cloud-clientlibs/README.rst b/contrib/opencensus-ext-google-cloud-clientlibs/README.rst index 14bb7835b..8d61a2d9a 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 ============================================================================ +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``. + +.. _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/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/contrib/opencensus-ext-httplib/README.rst b/contrib/opencensus-ext-httplib/README.rst index fe143a39d..d48feba6c 100644 --- a/contrib/opencensus-ext-httplib/README.rst +++ b/contrib/opencensus-ext-httplib/README.rst @@ -1,6 +1,14 @@ OpenCensus httplib Integration ============================================================================ +OpenCensus 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/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/contrib/opencensus-ext-requests/README.rst b/contrib/opencensus-ext-requests/README.rst index acbfb9051..169e593c5 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 ============================================================================ +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``. + +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..fb8317c0a 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 ============================================================================ +OpenCensus can propagate trace across threads when using the threading package. + +You can enable Threading integration by specifying ``'threading'`` to ``trace_integrations``. + Installation ------------ 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/requirements-test.txt b/requirements-test.txt index d272a446e..5712829e8 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -1,12 +1,9 @@ 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 WebOb==1.7.3 -wrapt==1.10.11 thrift==0.10.0 prometheus_client==0.5.0 diff --git a/setup.py b/setup.py index 0196efb48..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 @@ -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'], }