Allow clients to tag requests with a source_tag

pinecone-io / pinecone-python-client

The Pinecone Python client

https://www.pinecone.io/docs

Apache License 2.0

284 stars 78 forks source link

Allow clients to tag requests with a source_tag #324

Closed ssmith-pc closed 5 months ago

ssmith-pc commented 5 months ago

Problem

Need to allow clients to include a source_tag to identify the source of their requests.

Solution

Allow clients to specify a source_tag field in the client constructor, that will be used to identify the traffic source, if applicable.

Example:

from pinecone import Pinecone

pc = Pinecone(api_key='foo', source_tag='bar')

pc.list_indexes()

This would cause the user-agent to get a value like:

User-Agent: 'python-client-3.1.0 (urllib3:2.0.7); source_tag=bar'

Type of Change

[x] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Testing

[ ] Tests are passing
[ ] Verify source_tag included in user-agent in control plane and data plane (REST and gRPC)

jhamon commented 5 months ago

Something else to keep in mind is we would like to track usage of SDKs coming from our own higher-level tools in addition to external integration partners. For example,

canopy depends on the python sdk
spark-connector depends on java sdk

This doesn't change a ton about the general strategy, but it makes me think having partner in the name of these params isn't quite right.

jhamon commented 5 months ago

We should also reevaluate some of the cruft that's currently being passed in the user-agent strings. I've been here for a year and never had a need to know anything about what urllib3 version was in use.

ssmith-pc commented 5 months ago

We should also reevaluate some of the cruft that's currently being passed in the user-agent strings. I've been here for a year and never had a need to know anything about what urllib3 version was in use.

That's good to know that there isn't much relying on what's there currently. Would be nice to identify the high value information we'd like to capture and include.

I can understand how it could be helpful to know what http client/version is being used to access the service, particularly if there is a known bug with a particular version that causes trouble for our service, as this would likely help CS triage and help.

ssmith-pc commented 5 months ago

This doesn't change a ton about the general strategy, but it makes me think having partner in the name of these params isn't quite right.

Agree we should capture those clients, but I do wonder if we should try to keep the partner info separate. A lot of that depends on what we end up doing in the back-end, like how this info is extracted and matched up to what's in our partner CRM, etc.

In addition to setting the source_* fields, we could include a separate flag in our clients that identifies it as an internally owned integration.

jhamon commented 5 months ago

FYI there is a minimal unit test file called tests/unit/utils/test_user_agent.py that you may want to expand with a few more test cases to make sure the resulting string looks reasonable across a handful of different normalization cases.

ssmith-pc commented 5 months ago

FYI there is a minimal unit test file called tests/unit/utils/test_user_agent.py that you may want to expand with a few more test cases to make sure the resulting string looks reasonable across a handful of different normalization cases.

I was working on that concurrently with your comment -- just pushed