Package: signalfx
SignalFx was acquired by Splunk in October 2019. Seehttps://www.splunk.com/en_us/investor-relations/acquisitions/signalfx.htmlfor more information.Python client library for SignalFxThis is a programmatic interface in Python for SignalFx’s metadata and
ingest APIs. It is meant to provide a base for communicating with
SignalFx APIs that can be easily leveraged by scripts and applications
to interact with SignalFx or report metric and event data to SignalFx.
It is also the base for metric reporters that integrate with common
Python-based metric collections tools or libraries.InstallationTo install withpip:$pipinstallsignalfxTo install from source:$gitclonehttps://github.com/signalfx/signalfx-python.git$cdsignalfx-python/$pipinstall-e.UsageThis client library provides programmatic access to SignalFx’s APIs:the data ingest API;the metadata REST API;the SignalFlow API.You start by instantiating asignalfx.SignalFx()object, which then gives
you access to the API client that you want:importsignalfxsfx=signalfx.SignalFx(api_endpoint='https://api.{REALM}.signalfx.com',ingest_endpoint='https://ingest.{REALM}.signalfx.com',stream_endpoint='https://stream.{REALM}.signalfx.com')# For the ingest APIingest=sfx.ingest('ORG_TOKEN')# For the REST APIrest=sfx.rest('API_TOKEN')# For the SignalFlow APIflow=sfx.signalflow('ACCESS_TOKEN')If no endpoints are set manually, this library uses theus0realm by default.
If you are not in this realm, you will need to explicitly set the
endpoint urls above. To determine if you are in a different realm and need to
explicitly set the endpoints, check your profile page in the SignalFx
web application. You will also need to specify an access token when requesting
one of those clients. For the ingest client, you need to specify your
organization access token (which can be obtained from the
SignalFx organization you want to report data into). For the REST API,
you must use your user access token. For the SignalFlow client, either an
organization access token or a user access token may be used. For more
information on access tokens, see the API’sAuthentication documentation.Reporting dataBasic usage of the library for reporting data goes as follows:importsignalfxwithsignalfx.SignalFx().ingest('ORG_TOKEN')assfx:sfx.send(gauges=[{'metric':'myfunc.time','value':532,'timestamp':1442960607000},...],counters=[{'metric':'myfunc.calls','value':42,'timestamp':1442960607000},...],cumulative_counters=[{'metric':'myfunc.calls_cumulative','value':10,'timestamp':1442960607000},...])If you’re sending data from multiple places in your code, you should create
your ingest client once and use it throughout your application. Each ingest
client instance has an internal queue of datapoints and events that need to be
sent to SignalFx, as well as an internal thread draining that queue.When you
no longer need the client instance, make sure you call.stop()on it to
ensure the queue is fully drained.importsignalfxsfx=signalfx.SignalFx().ingest('ORG_TOKEN')try:sfx.send(...)sfx.send(...)finally:# Make sure that everything gets sent.sfx.stop()Thetimestampmust be a millisecond precision timestamp; the number of
milliseconds elapsed since Epoch. Thetimestampfield is optional, but
strongly recommended. If not specified, it will be set by SignalFx’s ingest
servers automatically; in this situation, the timestamp of your datapoints will
not accurately represent the time of their measurement (network latency,
batching, etc. will all impact when those datapoints actually make it to
SignalFx).When sending datapoints with multiple calls tosend(), it is recommended to
re-use the same SignalFx client object for eachsend()call.If you must use multiple client objects for the same token, which is not
recommended, it is important to callstop()after making allsend()calls. Each SignalFx client object uses a background thread to send datapoints
without blocking the caller. Callingstop()will gracefully flush the
thread’s send queue and close its TCP connections.Sending multi-dimensional dataReporting dimensions for the data is also optional, and can be accomplished by
specifying adimensionsparameter on each datapoint containing a dictionary
of string to string key/value pairs representing the dimensions:importsignalfxwithsignalfx.SignalFx().ingest('ORG_TOKEN')assfx:sfx.send(gauges=[{'metric':'myfunc.time','value':532,'timestamp':1442960607000,'dimensions':{'host':'server1','host_ip':'1.2.3.4'}},...],...)Seeexamples/generic_usecase.pyfor a complete code sample showing how to
send data to SignalFx.Sending eventsEvents can be sent to SignalFx via thesend_event()function. The event
type must be specified, and dimensions and extra event properties can be
supplied as well.importsignalfxwithsignalfx.SignalFx().ingest('ORG_TOKEN')assfx:sfx.send_event(event_type='deployments',dimensions={'host':'myhost','service':'myservice','instance':'myinstance'},properties={'version':'2015.04.29-01'})Metric metadata and tagsThe library includes functions to search, retrieve, and update metric
metadata and tags. Deleting tags is also supported.importsignalfxwithsignalfx.SignalFx().rest('ORG_TOKEN')assfx:sfx.update_tag('tag_name',description='An example tag',custom_properties={'version':'some_number'})AWS integrationOptionally, the client may be configured to append additional dimensions to all
metrics and events sent to SignalFx. One use case for this is to append the AWS
unique ID of the current host as an extra dimension. For example,importsignalfxfromsignalfx.awsimportAWS_ID_DIMENSION,get_aws_unique_idsfx=signalfx.SignalFx().ingest('ORG_TOKEN')# This dimension will be added to all datapoints sent.sfx.add_dimensions({AWS_ID_DIMENSION:get_aws_unique_id()})try:sfx.send(gauges=[{'metric':'myfunc.time','value':532,'timestamp':1442960607000,'dimensions':{'host':'server1','host_ip':'1.2.3.4'}},])finally:sfx.stop()Pyformance reporterpyformanceis a Python library that provides CodaHale-style metrics in a
very Pythonic way. We offer a reporter that can report thepyformancemetric registry data directly to SignalFx.fromsignalfx.pyformanceimport(count_calls,count_calls_with_dims,gauge,SignalFxReporter)@count_callsdefcallme():# whateverpass@count_calls_with_dims(dimension_key="dimension_value")defcallme_with_dims():# whateverpasssfx=SignalFxReporter(token='ORG_TOKEN')sfx.start()callme()callme()callme_with_dims()callme_with_dims()gauge('test').set_value(42)Seeexamples/pyformance_usecase.pyfor a complete code example using Pyformance.Executing SignalFlow computationsSignalFlow is SignalFx’s real-time analytics computation language. The
SignalFlow API allows SignalFx users to execute real-time streaming analytics
computations on the SignalFx platform. For more information, head over to our
Developers documentation:SignalFlow OverviewSignalFlow API ReferenceThe SignalFlow client accepts either an Organization Access Token or a User API Token.
Executing a SignalFlow program is very simple with this client library:importsignalfxprogram="data('cpu.utilization').mean().publish()"withsignalfx.SignalFx().signalflow('ACCESS_TOKEN')asflow:print('Executing{0}...'.format(program))computation=flow.execute(program)formsgincomputation.stream():ifisinstance(msg,signalfx.signalflow.messages.DataMessage):print('{0}:{1}'.format(msg.logical_timestamp_ms,msg.data))ifisinstance(msg,signalfx.signalflow.messages.EventMessage):print('{0}:{1}'.format(msg.timestamp_ms,msg.properties))Metadata about the streamed timeseries is received from.stream(), but it
is automatically intercepted by the client library and made available through
theComputationobject returned byexecute():ifisinstance(msg,signalfx.signalflow.messages.DataMessage):fortsid,valueinmsg.data.items():metadata=computation.get_metadata(tsid)# Display metadata and datapoint value as desiredFor more examples of how to execute SignalFlow computation with this library,
interpret and use the returned stream messages, you can look at the simple
example inexamples/signalflow/basic.pyor at theSignalFlow CLIand its
implementation which uses this library.Building a Pandas DataFrame from SignalFlow outputWith the SignalFlow output being programmatically accessible, it’s easy to
convert this data into any form that you need for further use or analysis. One
such use case is to build aPandas DataFramewith the computation’s output.
For a complete example of how to do this, seeexamples/signalflow/dataframe.py.Known IssuesSending only 1 datapoint and not seeing it in the chartThe reason you are not seeing the metrics in the chart is because the script
that is calling the Python client module is exiting right after calling the
send method. The Python client library is mainly targeted towards sending a
continuous stream of metrics and was implemented to be asynchronous.To work around this problem (most common in short-lived scripts for example),
register anatexitfunction to cleanly stop the datapoint sending thread
when your program exits:importatexitimportsignalfxsfx=signalfx.SignalFx().ingest('ORG_TOKEN')atexit.register(sfx.stop)SSLError when working with tags, metrics, dimensions, metrictimeseries, organizationERROR:root:Posting to SignalFx failed.
SSLError: hostname 'api.signalfx.com' doesn't match either of '*.signalfuse.com', 'signalfuse.com'.Root Cause: SignalFx’s API endpoints (api.signalfx.com,ingest.signalfx.comandstream.signalfx.com) have SSL SNI enabled and
theurllib3module in Python versions prior to 2.7.8 had a bug that causes
the above issue. This was fixed in later versions of Python; we recommend using
Python 2.7.9 or newer when using this library.Exceeding int64 integer sizesThe protocol buffer used to transmit data through the ingest API restricts
integers and longs to (-(2**63)to(2**63)-1).longvalues in
Python 2.x andintvalues in 3.x can exceed these values.  Any value or
property value less than-(2**63)or greater than(2**63)-1will raise
aValueErrorexception.LicenseApache Software License v2. Copyright © 2014-2019 SignalFx