{ "info": { "author": "Wavefront by VMware", "author_email": "chitimba@wavefront.com", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: Apache Software License", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7" ], "description": "# wavefront-sdk-python\n\n[![travis build status](https://travis-ci.com/wavefrontHQ/wavefront-sdk-python.svg?branch=master)](https://travis-ci.com/wavefrontHQ/wavefront-sdk-python)\n[![image](https://img.shields.io/pypi/v/wavefront-sdk-python.svg)](https://pypi.org/project/wavefront-sdk-python/)\n[![image](https://img.shields.io/pypi/l/wavefront-sdk-python.svg)](https://pypi.org/project/wavefront-sdk-python/)\n[![image](https://img.shields.io/pypi/pyversions/wavefront-sdk-python.svg)](https://pypi.org/project/wavefront-sdk-python/)\n\n\nWavefront by VMware SDK for Python is the core library for sending metrics, histograms and trace data from your Python application to Wavefront using via proxy or direct ingestion.\n\n## Requirements and Installation\nPython 2.7+ and Python 3.x are supported.\n\n```\npip install wavefront-sdk-python\n```\n\n## Set Up a Wavefront Sender\n\nYou can choose to send metrics, histograms, or trace data from your application to the Wavefront service using one of the following techniques:\n* Use [direct ingestion](https://docs.wavefront.com/direct_ingestion.html) to send the data directly to the Wavefront service. This is the simplest way to get up and running quickly.\n* Use a [Wavefront proxy](https://docs.wavefront.com/proxies.html), which then forwards the data to the Wavefront service. This is the recommended choice for a large-scale deployment that needs resilience to internet outages, control over data queuing and filtering, and more.\n\nYou instantiate an object that corresponds to your choice:\n* Option 1: [Create a `WavefrontDirectClient`](#option-1-create-a-wavefrontdirectclient) to send data directly to a Wavefront service.\n* Option 2: [Create a `WavefrontProxyClient`](#option-2-create-a-wavefrontproxyclient) to send data to a Wavefront proxy.\n\n### Option 1: Create a WavefrontDirectClient\nTo create a `WavefrontDirectClient`, you initialize it with the information it needs to send data directly to Wavefront.\n\n#### Step 1. Obtain Wavefront Access Information\nGather the following access information:\n\n* Identify the URL of your Wavefront instance. This is the URL you connect to when you log in to Wavefront, typically something like `https://mydomain.wavefront.com`.\n* In Wavefront, verify that you have Direct Data Ingestion permission, and [obtain an API token](http://docs.wavefront.com/wavefront_api.html#generating-an-api-token).\n\n#### Step 2. Initialize the WavefrontDirectClient\nYou initialize a `WavefrontDirectClient` by providing the access information you obtained in Step 1.\n\nYou can optionally specify parameters to tune the following ingestion properties:\n\n* Max queue size - Internal buffer capacity of the Wavefront sender. Any data in excess of this size is dropped.\n* Flush interval - Interval for flushing data from the Wavefront sender directly to Wavefront.\n* Batch size - Amount of data to send to Wavefront in each flush interval.\n\nTogether, the batch size and flush interval control the maximum theoretical throughput of the Wavefront sender. You should override the defaults _only_ to set higher values.\n\n\n```python\nfrom wavefront_sdk import WavefrontDirectClient\n\n# Create a sender with:\n # your Wavefront URL\n # a Wavefront API token that was created with direct ingestion permission\n # max queue size (in data points). Default: 50,000\n # batch size (in data points). Default: 10,000\n # flush interval (in seconds). Default: 1 second\nwavefront_sender = WavefrontDirectClient(\n server=\"\",\n token=\"\",\n max_queue_size=50000,\n batch_size=10000,\n flush_interval_seconds=5\n)\n```\n\n### Option 2: Create a WavefrontProxyClient\n\n**Note:** Before your application can use a `WavefrontProxyClient`, you must [set up and start a Wavefront proxy](https://github.com/wavefrontHQ/java/tree/master/proxy#set-up-a-wavefront-proxy).\n\nTo create a `WavefrontProxyClient`, you instantiate it with the information it needs to send data to a Wavefront proxy, including:\n\n* The name of the host that will run the Wavefront proxy.\n* One or more proxy listening ports to send data to. The ports you specify depend on the kinds of data you want to send (metrics, histograms, and/or trace data). You must specify at least one listener port.\n* Optional setting for tuning communication with the proxy.\n\n```python\nfrom wavefront_sdk import WavefrontProxyClient\n\n# Create a sender with:\n # the proxy hostname or address\n # the default listener port (2878) for sending metrics to\n # the recommended listener port (2878) for sending histograms to\n # the recommended listener port (30000) for sending trace data to\n # a nondefault interval (2 seconds) for flushing data from the sender to the proxy. Default: 5 seconds\nwavefront_sender = WavefrontProxyClient(\n host=\"\",\n metrics_port=2878,\n distribution_port=2878,\n tracing_port=30000,\n internal_flush=2\n)\n```\n\n**Note:** When you [set up a Wavefront proxy](https://github.com/wavefrontHQ/java/tree/master/proxy#set-up-a-wavefront-proxy) on the specified proxy host, you specify the port it will listen to for each type of data to be sent. The `WavefrontProxyClient` must send data to the same ports that the Wavefront proxy listens to. Consequently, the port-related parameters must specify the same port numbers as the corresponding proxy configuration properties:\n\n| `WavefrontProxyClient()` parameter | Corresponding property in `wavefront.conf` |\n| ----- | -------- |\n| `metrics_port` | `pushListenerPorts=` |\n| `distribution_port` | `histogramDistListenerPorts=` |\n| `tracing_port` | `traceListenerPorts=` |\n\n\n\n## Send a Single Data Point to Wavefront\n\nThe following examples show how to send a single data point to Wavefront. You use the Wavefront sender you created above.\n\n\n### Single Metric or Delta Counter\n\n```python\nfrom uuid import UUID\n\n# Wavefront metrics data format:\n# [] source= [pointTags]\nwavefront_sender.send_metric(\n name=\"new york.power.usage\", value=42422.0, timestamp=1533529977,\n source=\"localhost\", tags={\"datacenter\": \"dc1\"})\n\n# Wavefront delta counter data format:\n# source= [pointTags]\nwavefront_sender.send_delta_counter(\n name=\"delta.counter\", value=1.0,\n source=\"localhost\", tags={\"datacenter\": \"dc1\"})\n```\n### Single Histogram Distribution\n\n```python\nfrom uuid import UUID\nfrom wavefront_sdk.entities.histogram import histogram_granularity\n\n# Wavefront histogram data format:\n# {!M | !H | !D} [] # [centroids] source= [pointTags]\n# Example: You can choose to send to at most 3 bins: Minute, Hour, Day\n# \"!M 1533529977 #20 30.0 #10 5.1 request.latency source=appServer1 region=us-west\"\n# \"!H 1533529977 #20 30.0 #10 5.1 request.latency source=appServer1 region=us-west\"\n# \"!D 1533529977 #20 30.0 #10 5.1 request.latency source=appServer1 region=us-west\"\nwavefront_sender.send_distribution(\n name=\"request.latency\", centroids=[(30, 20), (5.1, 10)],\n histogram_granularities={histogram_granularity.DAY,\n histogram_granularity.HOUR,\n histogram_granularity.MINUTE},\n timestamp=1533529977, source=\"appServer1\", tags={\"region\": \"us-west\"})\n```\n\n### Single Span\n```python\nfrom uuid import UUID\n\n# Wavefront trace and span data format:\n# source= [pointTags] \n# Example: \"getAllUsers source=localhost\n# traceId=7b3bf470-9456-11e8-9eb6-529269fb1459\n# spanId=0313bafe-9457-11e8-9eb6-529269fb1459\n# parent=2f64e538-9457-11e8-9eb6-529269fb1459\n# application=Wavefront http.method=GET\n# 1533529977 343500\"\nwavefront_sender.send_span(\n name=\"getAllUsers\", start_millis=1533529977, duration_millis=343500,\n source=\"localhost\", trace_id=UUID(\"7b3bf470-9456-11e8-9eb6-529269fb1459\"),\n span_id=UUID(\"0313bafe-9457-11e8-9eb6-529269fb1459\"),\n parents=[UUID(\"2f64e538-9457-11e8-9eb6-529269fb1459\")],\n follows_from=None, tags=[(\"application\", \"Wavefront\"),\n (\"http.method\", \"GET\")],\n span_logs=None)\n```\n\n## Send Batch Data\n\nThe following examples show how to generate data points manually and send them as a batch to Wavefront.\n\n### Batch Metrics\n\n```python\nfrom uuid import UUID\nfrom wavefront_sdk.common import metric_to_line_data\n\n# Generate string data in Wavefront metric format\none_metric_data = metric_to_line_data(\n name=\"new-york.power.usage\", value=42422, timestamp=1493773500,\n source=\"localhost\", tags={\"datacenter\": \"dc1\"},\n default_source=\"defaultSource\")\n\n# Result of one_metric_data:\n # '\"new-york.power.usage\" 42422.0 1493773500 source=\"localhost\" \"datacenter\"=\"dc1\"\\n'\n\n# List of data\nbatch_metric_data = [one_metric_data, one_metric_data]\n\n# Send list of data immediately\nwavefront_sender.send_metric_now(batch_metric_data)\n```\n### Batch Histograms\n\n```python\nfrom uuid import UUID\nfrom wavefront_sdk.entities.histogram import histogram_granularity\nfrom wavefront_sdk.common import histogram_to_line_data\n\n# Generate string data in Wavefront histogram format\none_histogram_data = histogram_to_line_data(\n name=\"request.latency\", centroids=[(30.0, 20), (5.1, 10)],\n histogram_granularities={histogram_granularity.MINUTE,\n histogram_granularity.HOUR,\n histogram_granularity.DAY},\n timestamp=1493773500, source=\"appServer1\", tags={\"region\": \"us-west\"},\n default_source =\"defaultSource\")\n\n# Result of one_histogram_data:\n # '!D 1493773500 #20 30.0 #10 5.1 \"request.latency\" source=\"appServer1\" \"region\"=\"us-west\"\\n\n # !H 1493773500 #20 30.0 #10 5.1 \"request.latency\" source=\"appServer1\" \"region\"=\"us-west\"\\n\n # !M 1493773500 #20 30.0 #10 5.1 \"request.latency\" source=\"appServer1\" \"region\"=\"us-west\"\\n'\n\n# List of data\nbatch_histogram_data = [one_histogram_data, one_histogram_data]\n\n# Send list of data immediately\nwavefront_sender.send_distribution_now(batch_histogram_data)\n```\n### Batch Trace Data\n\n```python\nfrom uuid import UUID\nfrom wavefront_sdk.common import tracing_span_to_line_data\n\n# Generate string data in Wavefront tracing span format\none_tracing_span_data = tracing_span_to_line_data(\n name=\"getAllUsers\", start_millis=1552949776000, duration_millis=343,\n source=\"localhost\", trace_id=UUID(\"7b3bf470-9456-11e8-9eb6-529269fb1459\"),\n span_id=UUID(\"0313bafe-9457-11e8-9eb6-529269fb1459\"),\n parents=[UUID(\"2f64e538-9457-11e8-9eb6-529269fb1459\")],\n follows_from=[UUID(\"5f64e538-9457-11e8-9eb6-529269fb1459\")],\n tags=[(\"application\", \"Wavefront\"), (\"http.method\", \"GET\")],\n span_logs=None, default_source=\"defaultSource\")\n\n# Result of one_tracing_span_data:\n # '\"getAllUsers\" source=\"localhost\" traceId=7b3bf470-9456-11e8-9eb6-529269fb1459 spanId=0313bafe-\n # 9457-11e8-9eb6-529269fb1459 parent=2f64e538-9457-11e8-9eb6-529269fb1459 followsFrom=5f64e538-\n # 9457-11e8-9eb6-529269fb1459 \"application\"=\"Wavefront\" \"http.method\"=\"GET\" 1552949776000 343\\n'\n\n# List of data\nbatch_span_data = [one_tracing_span_data, one_tracing_span_data]\n\n# Send list of data immediately\nwavefront_sender.send_span_now(batch_span_data)\n```\n\n## Get a Failure Count\n\nIf there are any failures observed while sending metrics, histograms, or trace data, you can get the total failure count.\n\n```python\n# Get the total failure count\ntotal_failures = wavefront_sender.get_failure_count()\n```\n## Close the Connection\n\nIf the Wavefront sender is a `WavefrontDirectClient`, flush all buffers and then close the connection before shutting down the application.\n\n```python\n# To shut down a WavefrontDirectClient\n# Flush all buffers.\nwavefront_sender.flush_now()\n\n# Close the sender connection\nwavefront_sender.close()\n```\nIf the Wavefront sender is a `WavefrontProxyClient`, close the connection before shutting down the application.\n\n```python\n# To shut down a WavefrontProxyClient\n\n# Close the sender connection\nwavefront_sender.close()\n```", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/wavefrontHQ/wavefront-sdk-python", "keywords": "Wavefront,Wavefront SDK", "license": "Apache-2.0", "maintainer": "", "maintainer_email": "", "name": "wavefront-sdk-python", "package_url": "https://pypi.org/project/wavefront-sdk-python/", "platform": "", "project_url": "https://pypi.org/project/wavefront-sdk-python/", "project_urls": { "Homepage": "https://github.com/wavefrontHQ/wavefront-sdk-python" }, "release_url": "https://pypi.org/project/wavefront-sdk-python/1.4/", "requires_dist": null, "requires_python": "", "summary": "Wavefront Python SDK", "version": "1.4" }, "last_serial": 5980363, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "d61d780690ea39be6075b5afae348a42", "sha256": "7fdb96022089bdd9f6332e0eaa9fd7056fe038be13333d0109abda1807ef5351" }, "downloads": -1, "filename": "wavefront_sdk_python-1.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "d61d780690ea39be6075b5afae348a42", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 28476, "upload_time": "2018-12-14T06:00:38", "url": "https://files.pythonhosted.org/packages/f2/3b/65efa5908fb98ff82a3dc2f3fa8cf44910decbff00c1b5e6c4762dae109a/wavefront_sdk_python-1.0.0-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "2aff6df3a3eb2df3504d95e3d89fb696", "sha256": "562ad3137664c08ba767b610257153ebd81a83e86a8037982cb88b30368dde00" }, "downloads": -1, "filename": "wavefront-sdk-python-1.0.0.tar.gz", "has_sig": false, "md5_digest": "2aff6df3a3eb2df3504d95e3d89fb696", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 16366, "upload_time": "2018-12-14T06:00:40", "url": "https://files.pythonhosted.org/packages/e3/4e/e17d5f809d8df10dc24b456a61ad65bd390ce55eab3d12f976d26ebeaa37/wavefront-sdk-python-1.0.0.tar.gz" } ], "1.1.1": [ { "comment_text": "", "digests": { "md5": "3782642740577f997c6eaea03bb19e5f", "sha256": "34cd4d2afb489d88b7723ac1e51ebc392b18e5ecba273d38be77d8cb7a8005b6" }, "downloads": -1, "filename": "wavefront-sdk-python-1.1.1.tar.gz", "has_sig": false, "md5_digest": "3782642740577f997c6eaea03bb19e5f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 21599, "upload_time": "2019-03-20T23:02:58", "url": "https://files.pythonhosted.org/packages/66/7c/305f8535bff83832d50f596204cdbddb735dc7c3e209f9f0585751de011a/wavefront-sdk-python-1.1.1.tar.gz" } ], "1.2": [ { "comment_text": "", "digests": { "md5": "fc60b485dcbe0290ed39a0d5dad45c74", "sha256": "4903960a7ff8eed2fbbbfa31b5876514a22d5a9918e952eb28770588b86c752b" }, "downloads": -1, "filename": "wavefront-sdk-python-1.2.tar.gz", "has_sig": false, "md5_digest": "fc60b485dcbe0290ed39a0d5dad45c74", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22251, "upload_time": "2019-07-08T22:59:17", "url": "https://files.pythonhosted.org/packages/03/62/61365e544b9b0892929117f20fbd0d448e100c4a3e65830c9f8a6e38f1dd/wavefront-sdk-python-1.2.tar.gz" } ], "1.3": [ { "comment_text": "", "digests": { "md5": "eebc9e902d17588144c8c50c273cb867", "sha256": "5596bad023fd029fa1721aa4c242d293ac054ffa759084622c6687d61e157d00" }, "downloads": -1, "filename": "wavefront-sdk-python-1.3.tar.gz", "has_sig": false, "md5_digest": "eebc9e902d17588144c8c50c273cb867", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25282, "upload_time": "2019-10-11T22:06:52", "url": "https://files.pythonhosted.org/packages/d5/4b/665d9208a1fdb3ebd781d8b00f4a8e3be6c04ae2ce44392df03d748cf8a3/wavefront-sdk-python-1.3.tar.gz" } ], "1.4": [ { "comment_text": "", "digests": { "md5": "90db593a40e3b8440f75e11908a76838", "sha256": "e27bbe3bc113f72bd1676982feef3c77a470ff34f9b42ac30ccbf726b7d5e261" }, "downloads": -1, "filename": "wavefront-sdk-python-1.4.tar.gz", "has_sig": false, "md5_digest": "90db593a40e3b8440f75e11908a76838", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25486, "upload_time": "2019-10-15T23:28:22", "url": "https://files.pythonhosted.org/packages/f6/77/867f415a1b52156f0e4a0cee0f1cce495e31cca7e792538251cbf1bb1b2b/wavefront-sdk-python-1.4.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "90db593a40e3b8440f75e11908a76838", "sha256": "e27bbe3bc113f72bd1676982feef3c77a470ff34f9b42ac30ccbf726b7d5e261" }, "downloads": -1, "filename": "wavefront-sdk-python-1.4.tar.gz", "has_sig": false, "md5_digest": "90db593a40e3b8440f75e11908a76838", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25486, "upload_time": "2019-10-15T23:28:22", "url": "https://files.pythonhosted.org/packages/f6/77/867f415a1b52156f0e4a0cee0f1cce495e31cca7e792538251cbf1bb1b2b/wavefront-sdk-python-1.4.tar.gz" } ] }